@lotics/cli 0.292.3 → 0.294.0

package/docs/workflow_steps.md

@@ -0,0 +1,3694 @@
+<!-- Generated by backend/scripts/generate_workflow_steps_doc.ts from each step's schemas — never edit by hand. -->
+
+# Workflow steps
+
+The steps only a workflow body runs: a connection's (an invoice issuer, a mailbox, …) and the platform's own. Each is
+called as `await <step>({ ...inputs })` (see `workflows`); every other tool's inputs and answer are printed by
+`lotics tools <name>`.
+
+**How a step fails.** A step that is refused — an input the schema rejects, a connection the workspace lacks, an
+answer the provider refuses — ends the run, and the run's error reads `[<step>] <reason>`. Inside `try { … } catch
+(e) { … }` the body handles it instead: `e` is `{ message, type, step_id?, detail? }`, `message` the reason as
+above. A provider's refusal carries the provider's own words.
+
+## bkav
+
+### bkav_attach_files (workflow step)
+
+- Attach workspace files (a biên bản, a bảng kê) to an invoice on Bkav.
+- Bkav accepts PDF and Excel, at most 1 MB each.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guid` | string |  |  |
+| `partner_invoice_id` | string |  | Your PartnerInvoiceStringID, when invoice_guid is not set |
+| `file_ids` | string[] | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `results` | object[] | yes |  |
+| `results[].PartnerInvoiceID` | number | yes |  |
+| `results[].PartnerInvoiceStringID` | string \\| null | yes | Null on a delete's answer |
+| `results[].InvoiceGUID` | string | yes |  |
+| `results[].InvoiceForm` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceSerial` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |
+| `results[].MTC` | string \\| null | yes | Mã tra cứu the buyer looks the invoice up with; null on a draft's link answer |
+| `results[].MaCuaCQT` | string \\| null |  |  |
+| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |
+| `results[].MessLog` | string | yes |  |
+| `failed` | number | yes | Invoices whose own Status is not 0 |
+
+### bkav_cancel_invoices (workflow step)
+
+- Cancel issued invoices.
+- A cancelled invoice still reports to the tax authority; correcting one instead is a replacement or adjustment through bkav_submit_invoices. (workflow step)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guids` | string[] |  | InvoiceGUIDs Bkav returned |
+| `partner_invoice_ids` | string[] |  | Your PartnerInvoiceStringIDs |
+| `reason` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `results` | object[] | yes |  |
+| `results[].PartnerInvoiceID` | number | yes |  |
+| `results[].PartnerInvoiceStringID` | string \\| null | yes | Null on a delete's answer |
+| `results[].InvoiceGUID` | string | yes |  |
+| `results[].InvoiceForm` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceSerial` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |
+| `results[].MTC` | string \\| null | yes | Mã tra cứu the buyer looks the invoice up with; null on a draft's link answer |
+| `results[].MaCuaCQT` | string \\| null |  |  |
+| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |
+| `results[].MessLog` | string | yes |  |
+| `failed` | number | yes | Invoices whose own Status is not 0 |
+
+### bkav_create_bill (workflow step)
+
+- Record a cash-register bill on Bkav.
+- Field names are Bkav's.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `bill` | object | yes |  |
+| `bill.Bill` | object | yes |  |
+| `bill.Bill.BillCode` | number | yes |  |
+| `bill.Bill.OriginalBillCode` | number |  |  |
+| `bill.Bill.BillDate` | string | yes |  |
+| `bill.Bill.BillStatusID` | number | yes |  |
+| `bill.Bill.PayMethod` | string |  |  |
+| `bill.Bill.Note` | string |  |  |
+| `bill.ListBillDetails` | object[] | yes |  |
+| `bill.ListBillDetails[].ItemTypeID` | number |  | 0 goods, 4 description line, 15 promotional goods, … |
+| `bill.ListBillDetails[].IsDiscount` | boolean |  |  |
+| `bill.ListBillDetails[].ItemCode` | string |  |  |
+| `bill.ListBillDetails[].ItemName` | string | yes |  |
+| `bill.ListBillDetails[].UnitName` | string |  |  |
+| `bill.ListBillDetails[].Qty` | number |  |  |
+| `bill.ListBillDetails[].Price` | number |  |  |
+| `bill.ListBillDetails[].Amount` | number |  |  |
+| `bill.ListBillDetails[].TaxRateID` | number |  | 1 0%, 2 5%, 3 10%, 4 không chịu thuế, 9 8%, … |
+| `bill.ListBillDetails[].TaxRate` | number |  |  |
+| `bill.ListBillDetails[].TaxAmount` | number |  |  |
+| `bill.ListBillDetails[].OtherAmount` | number |  |  |
+| `bill.ListBillDetails[].DiscountRate` | number |  |  |
+| `bill.ListBillDetails[].DiscountAmount` | number |  |  |
+| `bill.ListBillDetails[].UserDefineDetails` | string |  |  |
+| `bill.ListBillDetails[].IsIncrease` | boolean \\| null |  | On an adjustment: true raises the amount, false lowers it, absent adjusts information |
+| `bill.ListBillDetails[].SpecialtyItems` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `created` | true | yes |  |
+
+### bkav_create_invoice_from_bills (workflow step)
+
+- Raise one invoice from cash-register bills, by their BillGUIDs.
+- Field names are Bkav's.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `input` | object | yes |  |
+| `input.Invoice` | object | yes |  |
+| `input.Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 bán hàng, 5 PXK kiêm VCNB, 6 PXK gửi bán đại lý |
+| `input.Invoice.InvoiceDate` | string | yes | ISO date |
+| `input.Invoice.BuyerCode` | string |  |  |
+| `input.Invoice.BuyerName` | string |  |  |
+| `input.Invoice.BuyerTaxCode` | string |  |  |
+| `input.Invoice.BuyerUnitName` | string |  |  |
+| `input.Invoice.BuyerAddress` | string |  |  |
+| `input.Invoice.BuyerBankAccount` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `input.Invoice.PayMethodID` | number |  | 1 TM, 2 CK, 3 TM/CK, … |
+| `input.Invoice.ReceiveTypeID` | number |  | 1 email, 2 SMS, 3 both, 4 courier |
+| `input.Invoice.ReceiverEmail` | string |  |  |
+| `input.Invoice.ReceiverMobile` | string |  |  |
+| `input.Invoice.ReceiverAddress` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `input.Invoice.ReceiverName` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `input.Invoice.Note` | string |  |  |
+| `input.Invoice.BillCode` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `input.Invoice.CurrencyID` | string |  |  |
+| `input.Invoice.ExchangeRate` | number |  |  |
+| `input.Invoice.InvoiceForm` | string |  | Mẫu số |
+| `input.Invoice.InvoiceSerial` | string |  | Ký hiệu |
+| `input.Invoice.InvoiceNo` | number |  | Số; 0 when Bkav assigns it |
+| `input.Invoice.MaCuaCQT` | string |  | Set only by a cash-register flow that already holds the authority's code |
+| `input.Invoice.UserDefine` | string |  | JSON-encoded template fields agreed with Bkav |
+| `input.Invoice.UIDefine` | string |  | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |
+| `input.Invoice.isBTH` | boolean |  |  |
+| `input.Invoice.CCCD` | string |  |  |
+| `input.Invoice.PassportNumber` | string |  |  |
+| `input.Invoice.FiscalCodes` | string |  |  |
+| `input.Invoice.Reason` | string |  | Why — required on a replacement or adjustment |
+| `input.Invoice.OriginalInvoiceIdentify` | string |  | `[mẫu số]_[ký hiệu]_[số]` of the invoice a replacement or adjustment corrects |
+| `input.Invoice.InvoiceGUID` | string |  | Addresses the invoice for an update by guid |
+| `input.BillGUIDs` | string[] | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `results` | object[] | yes |  |
+| `results[].PartnerInvoiceID` | number | yes |  |
+| `results[].PartnerInvoiceStringID` | string \\| null | yes | Null on a delete's answer |
+| `results[].InvoiceGUID` | string | yes |  |
+| `results[].InvoiceForm` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceSerial` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |
+| `results[].MTC` | string \\| null | yes | Mã tra cứu the buyer looks the invoice up with; null on a draft's link answer |
+| `results[].MaCuaCQT` | string \\| null |  |  |
+| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |
+| `results[].MessLog` | string | yes |  |
+| `failed` | number | yes | Invoices whose own Status is not 0 |
+
+### bkav_delete_invoices (workflow step)
+
+- Delete invoices that were never issued.
+- A numbered one can be deleted only if its number is the highest in its range.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guids` | string[] |  | InvoiceGUIDs Bkav returned |
+| `partner_invoice_ids` | string[] |  | Your PartnerInvoiceStringIDs |
+| `reason` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `results` | object[] | yes |  |
+| `results[].PartnerInvoiceID` | number | yes |  |
+| `results[].PartnerInvoiceStringID` | string \\| null | yes | Null on a delete's answer |
+| `results[].InvoiceGUID` | string | yes |  |
+| `results[].InvoiceForm` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceSerial` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |
+| `results[].MTC` | string \\| null | yes | Mã tra cứu the buyer looks the invoice up with; null on a draft's link answer |
+| `results[].MaCuaCQT` | string \\| null |  |  |
+| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |
+| `results[].MessLog` | string | yes |  |
+| `failed` | number | yes | Invoices whose own Status is not 0 |
+
+### bkav_explain_invoice_error (workflow step)
+
+- Explain an erroneous invoice to the tax authority without replacing or adjusting it, optionally answering one of its notices.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guid` | string | yes |  |
+| `reason` | string | yes |  |
+| `notice_number` | string |  | Số of the authority's notice being answered |
+| `notice_date` | string |  | yyyy-mm-dd; with notice_number |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `results` | object[] | yes |  |
+| `results[].InvoiceGUID` | string | yes |  |
+| `results[].Status` | number | yes | 0 succeeded; otherwise Msg says why |
+| `results[].Msg` | string | yes |  |
+| `failed` | number | yes | Invoices whose own Status is not 0 |
+
+### bkav_explain_replaced_invoice (workflow step)
+
+- Explain to the tax authority an invoice that was replaced or adjusted.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guid` | string | yes |  |
+| `reason` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `results` | object[] | yes |  |
+| `results[].InvoiceGUID` | string | yes |  |
+| `results[].Status` | number | yes | 0 succeeded; otherwise Msg says why |
+| `results[].Msg` | string | yes |  |
+| `failed` | number | yes | Invoices whose own Status is not 0 |
+
+### bkav_get_bill (workflow step)
+
+- Read a cash-register bill.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `seller_tax_code` | string | yes |  |
+| `organization_code` | string | yes |  |
+| `bill_code` | number | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `bill` | object | yes |  |
+
+### bkav_get_error_notice_pdf (workflow step)
+
+- Save the PDF of an invoice's 04/SS error notice as a workspace file.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the generated file. |
+| `url` | string | yes | The download URL of the generated file. |
+| `filename` | string | yes | The filename of the generated file, including extension. |
+| `mime_type` | string | yes | The MIME type of the generated file. |
+
+### bkav_get_file_by_lookup_code (workflow step)
+
+- Save an invoice's display copy, conversion copy or XML as a workspace file, found by the mã tra cứu the buyer was sent.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `lookup_code` | string | yes | Mã tra cứu |
+| `kind` | "display" \\| "converted" \\| "xml" | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the generated file. |
+| `url` | string | yes | The download URL of the generated file. |
+| `filename` | string | yes | The filename of the generated file, including extension. |
+| `mime_type` | string | yes | The MIME type of the generated file. |
+
+### bkav_get_invoice (workflow step)
+
+- Read one invoice as Bkav holds it — header, lines, status and mã tra cứu.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `id` | string | yes | Your PartnerInvoiceStringID or Bkav's InvoiceGUID |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `invoice` | object | yes |  |
+
+### bkav_get_invoice_file (workflow step)
+
+- Save an invoice's PDF or signed XML as a workspace file.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |
+| `format` | "pdf" \\| "xml" | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the generated file. |
+| `url` | string | yes | The download URL of the generated file. |
+| `filename` | string | yes | The filename of the generated file, including extension. |
+| `mime_type` | string | yes | The MIME type of the generated file. |
+
+### bkav_get_invoice_history (workflow step)
+
+- Read everything that happened to an invoice on Bkav, oldest first.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guid` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `entries` | object[] | yes |  |
+
+### bkav_get_invoice_link (workflow step)
+
+- Get a download link for an invoice's display copy, conversion copy, or its 04/SS error notice.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `partner_invoice_id` | string | yes | Your PartnerInvoiceStringID |
+| `kind` | "display" \\| "converted" \\| "notice_04ss" | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `url` | string | yes |  |
+
+### bkav_get_invoice_status (workflow step)
+
+- Read an invoice's status on Bkav.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guid` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `invoice_status_id` | number | yes | 1 mới tạo, 2 đã phát hành, 3 đã huỷ, 5–8 chờ/đã thay thế–điều chỉnh, 11 đã cấp số chờ ký |
+
+### bkav_get_listing (workflow step)
+
+- Save the bảng kê of one invoice type over a window as a workspace spreadsheet.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_type_id` | number | yes | 1 GTGT, 2 bán hàng, … |
+| `from_date` | string | yes | yyyy-mm-dd |
+| `to_date` | string | yes | yyyy-mm-dd |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the generated file. |
+| `url` | string | yes | The download URL of the generated file. |
+| `filename` | string | yes | The filename of the generated file, including extension. |
+| `mime_type` | string | yes | The MIME type of the generated file. |
+
+### bkav_get_report_bc26 (workflow step)
+
+- Save the BC26/AC invoice usage report for a window as a workspace XML file.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `from_date` | string | yes | yyyy-mm-dd |
+| `to_date` | string | yes | yyyy-mm-dd |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the generated file. |
+| `url` | string | yes | The download URL of the generated file. |
+| `filename` | string | yes | The filename of the generated file, including extension. |
+| `mime_type` | string | yes | The MIME type of the generated file. |
+
+### bkav_get_tax_status (workflow step)
+
+- Read the tax authority's status for an invoice and its mã của CQT once granted.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guid` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `statuses` | object[] | yes |  |
+| `statuses[].BkavStatus` | number | yes | InvoiceStatusID: 1 mới tạo, 2 đã phát hành, 3 đã huỷ, … |
+| `statuses[].TaxStatus` | number | yes | 32 waiting, 33 accepted, 34–39 returned or failed |
+| `statuses[].TaxAuthorityCode` | string \\| null | yes | Mã của Cơ quan thuế, once granted |
+| `statuses[].ErrorContent` | string \\| null | yes |  |
+
+### bkav_list_invoices_by_date (workflow step)
+
+- List invoices dated within a window, one page at a time.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `from_date` | string | yes | yyyy-mm-dd |
+| `to_date` | string | yes | yyyy-mm-dd |
+| `page` | number |  | 1-based |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `invoices` | object[] | yes |  |
+
+### bkav_list_invoices_by_number (workflow step)
+
+- List invoices of one mẫu số and ký hiệu by number range.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `form` | string | yes | Mẫu số |
+| `serial` | string | yes | Ký hiệu |
+| `from_number` | number | yes |  |
+| `to_number` | number | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `invoices` | object[] | yes |  |
+
+### bkav_lookup_company (workflow step)
+
+- Look up a company in the tax registry by Mã số thuế, through the Bkav account.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `tax_code` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `company` | object | yes |  |
+| `company.MaSoThue` | string | yes |  |
+| `company.TenChinhThuc` | string | yes |  |
+| `company.DiaChiGiaoDichChinh` | string | yes |  |
+| `company.DiaChiGiaoDichPhu` | string | yes |  |
+| `company.TrangThaiHoatDong` | string | yes |  |
+| `company.ChuDoanhNghiep` | string |  |  |
+| `company.SoDienThoai` | string \\| null |  |  |
+| `company.LastUpdate` | string |  |  |
+
+### bkav_send_lookup_email (workflow step)
+
+- Send an invoice's lookup email to the buyer again, or to another email or phone.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guid` | string | yes |  |
+| `email` | string |  |  |
+| `mobile` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `sent` | true | yes |  |
+
+### bkav_sign_invoices (workflow step)
+
+- Sign — issue — invoices with the account's HSM signature, making them tax-registered documents.
+- An account that signs with a USB token cannot sign this way.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `invoice_guids` | string[] | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `signed` | string[] | yes |  |
+
+### bkav_submit_invoices (workflow step)
+
+- Create, replace or adjust invoices on Bkav, in Bkav's field names.
+- Each carries PartnerInvoiceStringID, your own id for it, which Bkav uses to refuse a duplicate.
+- Attachments are not accepted here.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `kind` | "create_draft" \\| "create" \\| "create_draft_own_serial" \\| "create_own_number" \\| "create_own_serial" \\| "replace_draft" \\| "adjust_draft" \\| "adjust_discount_draft" \\| "replace" \\| "adjust" \\| "adjust_external_draft" \\| "adjust_discount" \\| "adjust_external" \\| "replace_external" \\| "replace_external_draft" | yes | create_draft: no number, deletable. create: Bkav numbers it. *_own_*: your form/serial. replace_* / adjust_*: each invoice names its original in Invoice.OriginalInvoiceIdentify and gives Invoice.Reason. *_external*: corrects an invoice issued outside Bkav; its first line is an ItemTypeID 4 description of it. *_draft kinds stay unnumbered. |
+| `invoices` | object[] | yes |  |
+| `invoices[].Invoice` | object | yes |  |
+| `invoices[].Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 bán hàng, 5 PXK kiêm VCNB, 6 PXK gửi bán đại lý |
+| `invoices[].Invoice.InvoiceDate` | string | yes | ISO date |
+| `invoices[].Invoice.BuyerCode` | string |  |  |
+| `invoices[].Invoice.BuyerName` | string |  |  |
+| `invoices[].Invoice.BuyerTaxCode` | string |  |  |
+| `invoices[].Invoice.BuyerUnitName` | string |  |  |
+| `invoices[].Invoice.BuyerAddress` | string |  |  |
+| `invoices[].Invoice.BuyerBankAccount` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `invoices[].Invoice.PayMethodID` | number |  | 1 TM, 2 CK, 3 TM/CK, … |
+| `invoices[].Invoice.ReceiveTypeID` | number |  | 1 email, 2 SMS, 3 both, 4 courier |
+| `invoices[].Invoice.ReceiverEmail` | string |  |  |
+| `invoices[].Invoice.ReceiverMobile` | string |  |  |
+| `invoices[].Invoice.ReceiverAddress` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `invoices[].Invoice.ReceiverName` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `invoices[].Invoice.Note` | string |  |  |
+| `invoices[].Invoice.BillCode` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `invoices[].Invoice.CurrencyID` | string |  |  |
+| `invoices[].Invoice.ExchangeRate` | number |  |  |
+| `invoices[].Invoice.InvoiceForm` | string |  | Mẫu số |
+| `invoices[].Invoice.InvoiceSerial` | string |  | Ký hiệu |
+| `invoices[].Invoice.InvoiceNo` | number |  | Số; 0 when Bkav assigns it |
+| `invoices[].Invoice.MaCuaCQT` | string |  | Set only by a cash-register flow that already holds the authority's code |
+| `invoices[].Invoice.UserDefine` | string |  | JSON-encoded template fields agreed with Bkav |
+| `invoices[].Invoice.UIDefine` | string |  | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |
+| `invoices[].Invoice.isBTH` | boolean |  |  |
+| `invoices[].Invoice.CCCD` | string |  |  |
+| `invoices[].Invoice.PassportNumber` | string |  |  |
+| `invoices[].Invoice.FiscalCodes` | string |  |  |
+| `invoices[].Invoice.Reason` | string |  | Why — required on a replacement or adjustment |
+| `invoices[].Invoice.OriginalInvoiceIdentify` | string |  | `[mẫu số]_[ký hiệu]_[số]` of the invoice a replacement or adjustment corrects |
+| `invoices[].Invoice.InvoiceGUID` | string |  | Addresses the invoice for an update by guid |
+| `invoices[].ListInvoiceDetailsWS` | object[] | yes |  |
+| `invoices[].ListInvoiceDetailsWS[].ItemTypeID` | number |  | 0 goods, 4 description line, 15 promotional goods, … |
+| `invoices[].ListInvoiceDetailsWS[].IsDiscount` | boolean |  |  |
+| `invoices[].ListInvoiceDetailsWS[].ItemCode` | string |  |  |
+| `invoices[].ListInvoiceDetailsWS[].ItemName` | string | yes |  |
+| `invoices[].ListInvoiceDetailsWS[].UnitName` | string |  |  |
+| `invoices[].ListInvoiceDetailsWS[].Qty` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].Price` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].Amount` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].TaxRateID` | number |  | 1 0%, 2 5%, 3 10%, 4 không chịu thuế, 9 8%, … |
+| `invoices[].ListInvoiceDetailsWS[].TaxRate` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].TaxAmount` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].OtherAmount` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].DiscountRate` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].DiscountAmount` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].UserDefineDetails` | string |  |  |
+| `invoices[].ListInvoiceDetailsWS[].IsIncrease` | boolean \\| null |  | On an adjustment: true raises the amount, false lowers it, absent adjusts information |
+| `invoices[].ListInvoiceDetailsWS[].SpecialtyItems` | string |  |  |
+| `invoices[].PartnerInvoiceStringID` | string | yes |  |
+| `invoices[].AttachListNumber` | string |  | Số of a bảng kê the invoice refers to |
+| `invoices[].AttachListDate` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `results` | object[] | yes |  |
+| `results[].PartnerInvoiceID` | number | yes |  |
+| `results[].PartnerInvoiceStringID` | string \\| null | yes | Null on a delete's answer |
+| `results[].InvoiceGUID` | string | yes |  |
+| `results[].InvoiceForm` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceSerial` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |
+| `results[].MTC` | string \\| null | yes | Mã tra cứu the buyer looks the invoice up with; null on a draft's link answer |
+| `results[].MaCuaCQT` | string \\| null |  |  |
+| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |
+| `results[].MessLog` | string | yes |  |
+| `failed` | number | yes | Invoices whose own Status is not 0 |
+
+### bkav_update_invoices (workflow step)
+
+- Change invoices not yet issued. by names how each invoice is found: partner (its partner id), number (Invoice.InvoiceForm + InvoiceSerial + InvoiceNo) or guid (Invoice.InvoiceGUID).
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Bkav connected account |
+| `by` | "partner" \\| "number" \\| "guid" | yes |  |
+| `invoices` | object[] | yes |  |
+| `invoices[].Invoice` | object | yes |  |
+| `invoices[].Invoice.InvoiceTypeID` | number | yes | 1 GTGT, 2 bán hàng, 5 PXK kiêm VCNB, 6 PXK gửi bán đại lý |
+| `invoices[].Invoice.InvoiceDate` | string | yes | ISO date |
+| `invoices[].Invoice.BuyerCode` | string |  |  |
+| `invoices[].Invoice.BuyerName` | string |  |  |
+| `invoices[].Invoice.BuyerTaxCode` | string |  |  |
+| `invoices[].Invoice.BuyerUnitName` | string |  |  |
+| `invoices[].Invoice.BuyerAddress` | string |  |  |
+| `invoices[].Invoice.BuyerBankAccount` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `invoices[].Invoice.PayMethodID` | number |  | 1 TM, 2 CK, 3 TM/CK, … |
+| `invoices[].Invoice.ReceiveTypeID` | number |  | 1 email, 2 SMS, 3 both, 4 courier |
+| `invoices[].Invoice.ReceiverEmail` | string |  |  |
+| `invoices[].Invoice.ReceiverMobile` | string |  |  |
+| `invoices[].Invoice.ReceiverAddress` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `invoices[].Invoice.ReceiverName` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `invoices[].Invoice.Note` | string |  |  |
+| `invoices[].Invoice.BillCode` | string |  | Sent empty when absent: Bkav refuses it missing |
+| `invoices[].Invoice.CurrencyID` | string |  |  |
+| `invoices[].Invoice.ExchangeRate` | number |  |  |
+| `invoices[].Invoice.InvoiceForm` | string |  | Mẫu số |
+| `invoices[].Invoice.InvoiceSerial` | string |  | Ký hiệu |
+| `invoices[].Invoice.InvoiceNo` | number |  | Số; 0 when Bkav assigns it |
+| `invoices[].Invoice.MaCuaCQT` | string |  | Set only by a cash-register flow that already holds the authority's code |
+| `invoices[].Invoice.UserDefine` | string |  | JSON-encoded template fields agreed with Bkav |
+| `invoices[].Invoice.UIDefine` | string |  | JSON-encoded delivery-note fields (InvoiceTypeID 5 and 6) |
+| `invoices[].Invoice.isBTH` | boolean |  |  |
+| `invoices[].Invoice.CCCD` | string |  |  |
+| `invoices[].Invoice.PassportNumber` | string |  |  |
+| `invoices[].Invoice.FiscalCodes` | string |  |  |
+| `invoices[].Invoice.Reason` | string |  | Why — required on a replacement or adjustment |
+| `invoices[].Invoice.OriginalInvoiceIdentify` | string |  | `[mẫu số]_[ký hiệu]_[số]` of the invoice a replacement or adjustment corrects |
+| `invoices[].Invoice.InvoiceGUID` | string |  | Addresses the invoice for an update by guid |
+| `invoices[].ListInvoiceDetailsWS` | object[] | yes |  |
+| `invoices[].ListInvoiceDetailsWS[].ItemTypeID` | number |  | 0 goods, 4 description line, 15 promotional goods, … |
+| `invoices[].ListInvoiceDetailsWS[].IsDiscount` | boolean |  |  |
+| `invoices[].ListInvoiceDetailsWS[].ItemCode` | string |  |  |
+| `invoices[].ListInvoiceDetailsWS[].ItemName` | string | yes |  |
+| `invoices[].ListInvoiceDetailsWS[].UnitName` | string |  |  |
+| `invoices[].ListInvoiceDetailsWS[].Qty` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].Price` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].Amount` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].TaxRateID` | number |  | 1 0%, 2 5%, 3 10%, 4 không chịu thuế, 9 8%, … |
+| `invoices[].ListInvoiceDetailsWS[].TaxRate` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].TaxAmount` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].OtherAmount` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].DiscountRate` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].DiscountAmount` | number |  |  |
+| `invoices[].ListInvoiceDetailsWS[].UserDefineDetails` | string |  |  |
+| `invoices[].ListInvoiceDetailsWS[].IsIncrease` | boolean \\| null |  | On an adjustment: true raises the amount, false lowers it, absent adjusts information |
+| `invoices[].ListInvoiceDetailsWS[].SpecialtyItems` | string |  |  |
+| `invoices[].PartnerInvoiceStringID` | string | yes |  |
+| `invoices[].AttachListNumber` | string |  | Số of a bảng kê the invoice refers to |
+| `invoices[].AttachListDate` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `results` | object[] | yes |  |
+| `results[].PartnerInvoiceID` | number | yes |  |
+| `results[].PartnerInvoiceStringID` | string \\| null | yes | Null on a delete's answer |
+| `results[].InvoiceGUID` | string | yes |  |
+| `results[].InvoiceForm` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceSerial` | string \\| null | yes | Null on a draft's link answer |
+| `results[].InvoiceNo` | number | yes | Assigned by a numbered kind; 0 on a draft |
+| `results[].MTC` | string \\| null | yes | Mã tra cứu the buyer looks the invoice up with; null on a draft's link answer |
+| `results[].MaCuaCQT` | string \\| null |  |  |
+| `results[].Status` | number | yes | 0 succeeded; otherwise MessLog says why |
+| `results[].MessLog` | string | yes |  |
+| `failed` | number | yes | Invoices whose own Status is not 0 |
+
+## drive
+
+### drive_export_file (workflow step)
+
+- Upload a Lotics file to the member's Google Drive.
+- The file is uploaded as-is — a .docx stays a .docx, a .xlsx stays a .xlsx.
+- It is deliberately NOT converted into a Google Doc or Sheet: conversion re-flows the layout of a generated document, and a native Google file is live, so its figures would drift away from the record they came from.
+- Use this to archive a finished document, the way you would attach it to an email.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The ID of the connected Google Drive account to use |
+| `file_id` | string | yes | Lotics file ID to upload |
+| `folder_id` | string |  | Drive folder ID to place the file in; omit for the member's Drive root |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `drive_file_id` | string | yes | Drive file ID of the uploaded copy |
+| `web_view_link` | string \\| null | yes | URL to open the uploaded file in Drive |
+
+### drive_import_file (workflow step)
+
+- Import a Google Drive file into the workspace as a Lotics file, and return its file id.
+- Google Docs arrive as .docx, Sheets as .xlsx, Slides as .pptx; everything else transfers unchanged. **This is also how you READ a Drive file.** There is no separate Drive read tool: import the file, then use `view_files` on the returned id. (workflow step, chat)
+- That path handles scanned documents — a photographed B/L or a stamped invoice inside a .docx reaches the model as a picture.
+- Exporting Drive content as plain text would return an empty document for exactly those files.
+- Folders, Forms, shortcuts and other Drive items with no file form cannot be imported.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The ID of the connected Google Drive account to use |
+| `file_id` | string | yes | Drive file ID, from drive_query_files (workflow step, chat) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `id` | string | yes | Lotics file ID — pass this to view_files to read the contents (workflow step, chat) |
+| `filename` | string | yes |  |
+| `mime_type` | string | yes |  |
+| `url` | string | yes |  |
+
+### drive_query_files (workflow step)
+
+- Search the member's Google Drive using Drive query syntax. ## Query syntax Terms are `field operator value`; combine with `and` / `or` / `not`.
+- String values are single-quoted. - Name: `name = 'Rate card'`, `name contains 'invoice'` - Full text (body + title): `fullText contains 'CMA CGM'` - Type: `mimeType = 'application/vnd.google-apps.spreadsheet'`, `mimeType contains 'pdf'` - Folder: `'<folder_id>' in parents` - Time (RFC 3339): `modifiedTime > '2026-01-01T00:00:00'` - Exclude deleted: `trashed = false` (always worth adding) - Starred / shared: `starred = true`, `sharedWithMe = true` Google-native types: `application/vnd.google-apps.document` (Docs), `.spreadsheet` (Sheets), `.presentation` (Slides), `.folder`.
+- Examples: - `name contains 'packing list' and trashed = false` - `'1a2b3c' in parents and modifiedTime > '2026-08-01T00:00:00'` - `fullText contains 'demurrage' and mimeType = 'application/vnd.google-apps.document'` Results carry enough metadata (name, type, modified time, size, owner) to pick a file WITHOUT importing it.
+- Import only the one you actually need — `drive_import_file` persists a copy in the workspace. (workflow step, chat)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The ID of the connected Google Drive account to use |
+| `query` | string | yes | Drive query syntax expression |
+| `max_result` | number | yes | Maximum number of files to retrieve (1-50) |
+| `order_by` | string |  | Sort order, e.g. 'modifiedTime desc', 'name' |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `files` | object[] | yes | List of matching Drive files |
+| `files[].id` | string | yes | Drive file ID — pass this to drive_import_file (workflow step, chat) |
+| `files[].name` | string | yes | File name as it appears in Drive |
+| `files[].mime_type` | string | yes | Drive MIME type; 'application/vnd.google-apps.*' means Google-native |
+| `files[].modified_time` | string \\| null | yes | RFC 3339 timestamp of the last modification |
+| `files[].size_bytes` | number \\| null | yes | Size in bytes; null for Google-native files, which have no stored size until exported |
+| `files[].owner` | string \\| null | yes | Email address of the file's owner |
+| `files[].web_view_link` | string \\| null | yes | URL to open the file in Drive |
+
+## evaluate
+
+### evaluate_formula (workflow step)
+
+- Compute a formula over one record as its table's own formula fields compute: fields referenced as `{fld_…}`, lookups and rollups read as the row holds them.
+- Writes nothing.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `table_id` | string | yes |  |
+| `record_id` | string | yes |  |
+| `expression` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `value` | number \\| string \\| boolean \\| null | yes |  |
+
+## excel
+
+### excel_create_file (workflow step)
+
+- Create an Excel file with styled column headers and auto-filter enabled.
+- Input: { filename, sheets: [{ name, columns: [{ header, width? }], rows: unknown[][] }] } Headers are bold, centered, bordered, with auto-filter on the header row.
+- Best for producing polished report-style spreadsheets.
+- Returns a new file_id — use it for subsequent operations.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `sheets` | object[] | yes |  |
+| `sheets[].name` | string | yes |  |
+| `sheets[].columns` | object[] | yes |  |
+| `sheets[].columns[].header` | string | yes |  |
+| `sheets[].columns[].width` | number |  |  |
+| `sheets[].rows` | any[][] | yes | 2D array of cell values |
+| `filename` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the generated file. |
+| `url` | string | yes | The download URL of the generated file. |
+| `filename` | string | yes | The filename of the generated file, including extension. |
+| `mime_type` | string | yes | The MIME type of the generated file. |
+
+### excel_find_cells (workflow step)
+
+- Search for cells matching a text query in an Excel worksheet.
+- Input: { file_id, worksheet: string\|number, query: "search text", match_type?: "contains"\|"exact"\|"regex", max_results?: number } Default match_type is "contains" (case-insensitive).
+- Returns matching cell addresses, values, and positions.
+- Read-only — does not modify the file.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `worksheet` | string \\| number | yes |  |
+| `query` | string | yes | Text to find. |
+| `match_type` | "exact" \\| "contains" \\| "regex" |  | How to match: exact, contains (default), or regex |
+| `max_results` | number |  | Max matches to return |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `matches` | object[] | yes |  |
+| `matches[].cell` | string | yes | Cell address, e.g. B3 |
+| `matches[].value` | string | yes | Cell value as string |
+| `matches[].row` | number | yes | Row number |
+| `matches[].column` | string | yes | Column letter |
+| `total_matches` | number | yes | Total number of matches found |
+
+### excel_format_range (workflow step)
+
+- Apply formatting to a cell range (fonts, fills, borders, alignment, number formats). range format is always "START:END" — single cell: "B2:B2", multi-cell: "A1:D10".
+- Never use "B2" alone.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `worksheet` | string \\| number | yes |  |
+| `range` | string | yes |  |
+| `format` | object | yes |  |
+| `format.font_bold` | boolean |  |  |
+| `format.font_italic` | boolean |  |  |
+| `format.font_size` | number |  |  |
+| `format.font_color` | string |  | Hex color like #FF0000 |
+| `format.font_name` | string |  |  |
+| `format.font_underline` | "single" \\| "double" |  |  |
+| `format.font_strike` | boolean |  |  |
+| `format.background_color` | string |  | Hex color like #FFFF00 |
+| `format.horizontal_align` | "left" \\| "center" \\| "right" |  |  |
+| `format.vertical_align` | "top" \\| "middle" \\| "bottom" |  |  |
+| `format.wrap_text` | boolean |  |  |
+| `format.number_format` | string |  | Excel number format code (e.g. #,##0.00, dd/mm/yyyy) |
+| `format.border_top` | object |  |  |
+| `format.border_top.style` | "solid" \\| "dashed" \\| "dotted" \\| "double" |  |  |
+| `format.border_top.width` | number |  |  |
+| `format.border_top.color` | string |  |  |
+| `format.border_bottom` | object |  |  |
+| `format.border_bottom.style` | "solid" \\| "dashed" \\| "dotted" \\| "double" |  |  |
+| `format.border_bottom.width` | number |  |  |
+| `format.border_bottom.color` | string |  |  |
+| `format.border_left` | object |  |  |
+| `format.border_left.style` | "solid" \\| "dashed" \\| "dotted" \\| "double" |  |  |
+| `format.border_left.width` | number |  |  |
+| `format.border_left.color` | string |  |  |
+| `format.border_right` | object |  |  |
+| `format.border_right.style` | "solid" \\| "dashed" \\| "dotted" \\| "double" |  |  |
+| `format.border_right.width` | number |  |  |
+| `format.border_right.color` | string |  |  |
+| `column_widths` | object |  | Column letter → width mapping |
+| `row_heights` | object |  | Row number → height mapping |
+| `auto_filter` | string |  | Range for an auto-filter (e.g. A1:D1); one over a table turns on that table's own filter |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `formatted_cells` | number | yes |  |
+
+### excel_get_range (workflow step)
+
+- Read cell values from a range in an Excel worksheet. range format is always "START:END" — single cell: "B2:B2", multi-cell: "A1:D10".
+- Never use "B2" alone. worksheet: use sheet name (preferred) or 0-based index.
+- Use view_file first to see available worksheets.
+- Returns data keyed by row number then column letter, e.g. { "1": { "A": "Hello" } }.
+- Maximum 1000 cells per call — use smaller ranges and paginate if needed.
+- Read-only — does not modify the file.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `worksheet` | string \\| number | yes |  |
+| `range` | string | yes |  |
+| `options` | object |  | Options for data retrieval |
+| `options.include_formulas` | boolean |  | Include cell formulas instead of calculated values |
+| `options.include_formatting` | boolean |  | Include cell formatting information |
+| `options.max_cell_length` | number |  | Max characters returned per cell; longer text is truncated with an ellipsis. Pass -1 to return cells in full — use when reading free-text columns like notes. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `worksheet_name` | string | yes | The worksheet name |
+| `range` | string | yes | The requested range |
+| `data` | object | yes | Cell values keyed by row number then column letter |
+| `formatting` | object |  | Cell formatting keyed by row then column |
+| `truncated_cells` | object[] |  | Cells with truncated content |
+| `truncated_cells[].cell` | string | yes | Cell address |
+| `truncated_cells[].original_length` | number | yes | Original text length |
+
+### excel_update_range (workflow step)
+
+- Write cell values into a range in an Excel worksheet. range format is always "START:END" — single cell: "B2:B2", multi-cell: "A1:C3".
+- Never use "B2" alone. values is a 2D array matching the range dimensions.
+- Single cell: [["value"]], row: [["a","b","c"]], grid: [[r1...],[r2...]].
+- Strings starting with "=" are interpreted as formulas (e.g. "=SUM(A1:A10)").
+- Set options.interpret_formulas=false to write literal "=" text.
+- Modifies the document in place.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `worksheet` | string \\| number | yes |  |
+| `range` | string | yes |  |
+| `values` | any[][] | yes | 2D array of values to write (rows x columns) |
+| `options` | object |  |  |
+| `options.preserve_formatting` | boolean |  | Preserve existing cell formatting (only update values) |
+| `options.apply_number_format` | string |  | Apply a number format to all cells in the range (e.g., '#,##0.00') |
+| `options.interpret_formulas` | boolean |  | Set false to write '=' strings as literal text |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `worksheet_name` | string | yes |  |
+| `range` | string | yes |  |
+| `updated_cells` | number | yes | Number of cells updated |
+
+## facebook
+
+### facebook_create_post (workflow step)
+
+- Publish a post to a Facebook Page feed.
+- Requires a Facebook connected account whose page allows content management.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `page_id` | string | yes | Facebook Page to post to — one of the connected account's managed pages. |
+| `message` | string | yes |  |
+| `link` | string |  | A post carries either a link or media. |
+| `media_file_ids` | string[] |  | Photos, or one video on its own. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `post_id` | string | yes |  |
+| `url` | string | yes |  |
+
+### facebook_list_comments (workflow step)
+
+- Read the most recent comments left on a Facebook Page's posts.
+- Reply with facebook_reply_to_comment, passing the comment_id. (workflow step)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `page_id` | string | yes | One of the connected account's managed pages. |
+| `limit` | integer |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `comments` | object[] | yes |  |
+| `comments[].comment_id` | string | yes |  |
+| `comments[].post_id` | string | yes |  |
+| `comments[].author_id` | string | yes |  |
+| `comments[].author_name` | string | yes |  |
+| `comments[].message` | string | yes |  |
+| `comments[].created_time` | string | yes |  |
+
+### facebook_list_conversations (workflow step)
+
+- Read a Facebook Page's Messenger conversations with their recent messages.
+- Answer someone with facebook_send_message, passing the person_id. (workflow step)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `page_id` | string | yes | One of the connected account's managed pages. |
+| `limit` | integer |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `conversations` | object[] | yes |  |
+| `conversations[].conversation_id` | string | yes |  |
+| `conversations[].person_id` | string \\| null | yes |  |
+| `conversations[].person_name` | string \\| null | yes |  |
+| `conversations[].messages` | object[] | yes |  |
+| `conversations[].messages[].from_id` | string | yes |  |
+| `conversations[].messages[].from_name` | string | yes |  |
+| `conversations[].messages[].message` | string | yes |  |
+| `conversations[].messages[].created_time` | string | yes |  |
+
+### facebook_reply_to_comment (workflow step)
+
+- Reply publicly to a comment on a Facebook Page post, as the page.
+- The reply is visible to everyone who can see the comment.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `page_id` | string | yes | The page that owns the post the comment is on. |
+| `comment_id` | string | yes | From facebook_list_comments. (workflow step) |
+| `message` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `comment_id` | string | yes | The reply's own id. |
+
+### facebook_send_message (workflow step)
+
+- Answer someone who messaged a Facebook Page, as the page.
+- Meta accepts a reply only within 24 hours of that person's last message.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `page_id` | string | yes | The page the person wrote to. |
+| `person_id` | string | yes | From facebook_list_conversations. Page-scoped to this page. (workflow step) |
+| `message` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message_id` | string | yes |  |
+
+## fedex
+
+### fedex_cancel_draft (workflow step)
+
+- Cancel (delete) an unconfirmed FedEx draft (Open Ship) booking by its reference.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | FedEx connected account |
+| `reference` | string | yes | The draft's reference (Open Ship index) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `cancelled` | boolean | yes |  |
+
+### fedex_confirm_shipment (workflow step)
+
+- Confirm a FedEx draft (Open Ship) booking by its reference, generating the label / AWB.
+- Returns the master tracking number and any piece tracking numbers + label URLs.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | FedEx connected account |
+| `reference` | string | yes | The draft's reference (Open Ship index) from fedex_create_draft_shipment (workflow step) |
+| `master_tracking_number` | string |  | The master_tracking_number returned by fedex_create_draft_shipment — required to finalize the label (workflow step) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `master_tracking_number` | string |  |  |
+| `tracking_numbers` | string[] | yes |  |
+| `label_urls` | string[] | yes |  |
+
+### fedex_create_draft_shipment (workflow step)
+
+- Create a FedEx draft (Open Ship) booking — no label yet.
+- Confirm later with fedex_confirm_shipment. reference is a unique key you choose (e.g. the shipment order number) used to confirm or cancel. (workflow step)
+- Supports multiple packages, special services, and (international) customs commodities.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | FedEx connected account |
+| `reference` | string | yes | Unique key for this draft (the Open Ship index) |
+| `shipper` | object | yes |  |
+| `shipper.contact` | object |  |  |
+| `shipper.contact.person_name` | string |  |  |
+| `shipper.contact.company_name` | string |  |  |
+| `shipper.contact.phone_number` | string |  |  |
+| `shipper.address` | object | yes |  |
+| `shipper.address.postal_code` | string | yes |  |
+| `shipper.address.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |
+| `shipper.address.city` | string |  |  |
+| `shipper.address.state_or_province_code` | string |  |  |
+| `shipper.address.street_lines` | string[] |  |  |
+| `shipper.address.residential` | boolean |  |  |
+| `recipient` | object | yes |  |
+| `recipient.contact` | object |  |  |
+| `recipient.contact.person_name` | string |  |  |
+| `recipient.contact.company_name` | string |  |  |
+| `recipient.contact.phone_number` | string |  |  |
+| `recipient.address` | object | yes |  |
+| `recipient.address.postal_code` | string | yes |  |
+| `recipient.address.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |
+| `recipient.address.city` | string |  |  |
+| `recipient.address.state_or_province_code` | string |  |  |
+| `recipient.address.street_lines` | string[] |  |  |
+| `recipient.address.residential` | boolean |  |  |
+| `service_type` | string | yes | FedEx service type e.g. INTERNATIONAL_PRIORITY |
+| `packaging_type` | string |  | FedEx packaging type e.g. YOUR_PACKAGING |
+| `packages` | object[] | yes | One entry per package; weight in kg |
+| `packages[].weight` | number | yes |  |
+| `packages[].weight_units` | "KG" \\| "LB" |  | Weight units; FedEx requires LB for US domestic express |
+| `packages[].length` | number |  |  |
+| `packages[].width` | number |  |  |
+| `packages[].height` | number |  |  |
+| `packages[].dimension_units` | "CM" \\| "IN" |  |  |
+| `ship_datestamp` | string |  | Ship date YYYY-MM-DD |
+| `pickup_type` | string |  | FedEx pickup type e.g. USE_SCHEDULED_PICKUP |
+| `special_services` | string[] |  | FedEx special service types e.g. SATURDAY_DELIVERY, FEDEX_ONE_RATE |
+| `commodities` | object[] |  | Customs commodities for international shipments |
+| `commodities[].description` | string | yes |  |
+| `commodities[].quantity` | number | yes |  |
+| `commodities[].customs_value` | number | yes |  |
+| `commodities[].currency` | string | yes |  |
+| `commodities[].weight` | number | yes |  |
+| `commodities[].weight_units` | "KG" \\| "LB" |  |  |
+| `commodities[].country_of_manufacture` | string |  | ISO 3166-1 alpha-2 |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `reference` | string | yes |  |
+| `status` | "draft" | yes |  |
+| `master_tracking_number` | string |  | Pass this to fedex_confirm_shipment to finalize the draft (workflow step) |
+
+### fedex_create_shipment (workflow step)
+
+- Create a FedEx shipment and generate the label / AWB in one call.
+- Returns the master tracking number, piece tracking numbers, and label URLs.
+- Use the Open Ship draft flow instead when you need to stage a booking before committing.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | FedEx connected account |
+| `shipper` | object | yes |  |
+| `shipper.contact` | object |  |  |
+| `shipper.contact.person_name` | string |  |  |
+| `shipper.contact.company_name` | string |  |  |
+| `shipper.contact.phone_number` | string |  |  |
+| `shipper.address` | object | yes |  |
+| `shipper.address.postal_code` | string | yes |  |
+| `shipper.address.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |
+| `shipper.address.city` | string |  |  |
+| `shipper.address.state_or_province_code` | string |  |  |
+| `shipper.address.street_lines` | string[] |  |  |
+| `shipper.address.residential` | boolean |  |  |
+| `recipient` | object | yes |  |
+| `recipient.contact` | object |  |  |
+| `recipient.contact.person_name` | string |  |  |
+| `recipient.contact.company_name` | string |  |  |
+| `recipient.contact.phone_number` | string |  |  |
+| `recipient.address` | object | yes |  |
+| `recipient.address.postal_code` | string | yes |  |
+| `recipient.address.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |
+| `recipient.address.city` | string |  |  |
+| `recipient.address.state_or_province_code` | string |  |  |
+| `recipient.address.street_lines` | string[] |  |  |
+| `recipient.address.residential` | boolean |  |  |
+| `service_type` | string | yes | FedEx service type e.g. INTERNATIONAL_PRIORITY |
+| `packaging_type` | string |  | FedEx packaging type e.g. YOUR_PACKAGING |
+| `packages` | object[] | yes | One entry per package; weight in kg |
+| `packages[].weight` | number | yes |  |
+| `packages[].weight_units` | "KG" \\| "LB" |  | Weight units; FedEx requires LB for US domestic express |
+| `packages[].length` | number |  |  |
+| `packages[].width` | number |  |  |
+| `packages[].height` | number |  |  |
+| `packages[].dimension_units` | "CM" \\| "IN" |  |  |
+| `ship_datestamp` | string |  | Ship date YYYY-MM-DD |
+| `pickup_type` | string |  | FedEx pickup type e.g. USE_SCHEDULED_PICKUP |
+| `special_services` | string[] |  | FedEx special service types |
+| `commodities` | object[] |  | Customs commodities for international shipments |
+| `commodities[].description` | string | yes |  |
+| `commodities[].quantity` | number | yes |  |
+| `commodities[].customs_value` | number | yes |  |
+| `commodities[].currency` | string | yes |  |
+| `commodities[].weight` | number | yes |  |
+| `commodities[].weight_units` | "KG" \\| "LB" |  |  |
+| `commodities[].country_of_manufacture` | string |  | ISO 3166-1 alpha-2 |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `master_tracking_number` | string |  |  |
+| `tracking_numbers` | string[] | yes |  |
+| `label_urls` | string[] | yes |  |
+
+### fedex_rate (workflow step)
+
+- Get FedEx rate quotes for a shipment.
+- Returns one priced row per available service (or just the requested service_type).
+- Use before booking to compare costs.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | FedEx connected account |
+| `shipper` | object | yes |  |
+| `shipper.postal_code` | string | yes |  |
+| `shipper.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |
+| `shipper.city` | string |  |  |
+| `shipper.state_or_province_code` | string |  |  |
+| `shipper.street_lines` | string[] |  |  |
+| `shipper.residential` | boolean |  |  |
+| `recipient` | object | yes |  |
+| `recipient.postal_code` | string | yes |  |
+| `recipient.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |
+| `recipient.city` | string |  |  |
+| `recipient.state_or_province_code` | string |  |  |
+| `recipient.street_lines` | string[] |  |  |
+| `recipient.residential` | boolean |  |  |
+| `packages` | object[] | yes | One entry per package; weight in kg |
+| `packages[].weight` | number | yes |  |
+| `packages[].weight_units` | "KG" \\| "LB" |  | Weight units; FedEx requires LB for US domestic express |
+| `packages[].length` | number |  |  |
+| `packages[].width` | number |  |  |
+| `packages[].height` | number |  |  |
+| `packages[].dimension_units` | "CM" \\| "IN" |  |  |
+| `service_type` | string |  | FedEx service type e.g. INTERNATIONAL_PRIORITY. Omit to rate all available services. |
+| `packaging_type` | string |  | FedEx packaging type e.g. YOUR_PACKAGING |
+| `pickup_type` | string |  | FedEx pickup type e.g. USE_SCHEDULED_PICKUP |
+| `ship_datestamp` | string |  | Ship date YYYY-MM-DD |
+| `special_services` | string[] |  | FedEx special service types e.g. SATURDAY_DELIVERY |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `services` | object[] | yes |  |
+| `services[].service_type` | string | yes |  |
+| `services[].service_name` | string |  |  |
+| `services[].total_charge` | number |  |  |
+| `services[].currency` | string |  |  |
+
+### fedex_service_availability (workflow step)
+
+- Check what FedEx services serve a lane. query "transit_times" returns delivery commitments per service; "package_and_service_options" returns valid service/packaging combinations; "special_service_options" returns available special services.
+- Use before rating/booking to learn the valid service types for an origin → destination.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | FedEx connected account |
+| `query` | "transit_times" \\| "special_service_options" \\| "package_and_service_options" | yes |  |
+| `shipper` | object | yes |  |
+| `shipper.postal_code` | string | yes |  |
+| `shipper.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |
+| `shipper.city` | string |  |  |
+| `shipper.state_or_province_code` | string |  |  |
+| `shipper.street_lines` | string[] |  |  |
+| `shipper.residential` | boolean |  |  |
+| `recipient` | object | yes |  |
+| `recipient.postal_code` | string | yes |  |
+| `recipient.country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |
+| `recipient.city` | string |  |  |
+| `recipient.state_or_province_code` | string |  |  |
+| `recipient.street_lines` | string[] |  |  |
+| `recipient.residential` | boolean |  |  |
+| `packages` | object[] | yes | One entry per package; weight in kg unless weight_units set |
+| `packages[].weight` | number | yes |  |
+| `packages[].weight_units` | "KG" \\| "LB" |  | Weight units; FedEx requires LB for US domestic express |
+| `packages[].length` | number |  |  |
+| `packages[].width` | number |  |  |
+| `packages[].height` | number |  |  |
+| `packages[].dimension_units` | "CM" \\| "IN" |  |  |
+| `ship_datestamp` | string |  | Ship date YYYY-MM-DD |
+| `carrier_codes` | string[] | yes | FedEx carrier codes — at least one, e.g. FDXE (Express), FDXG (Ground) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `result` | object | yes |  |
+
+### fedex_validate_address (workflow step)
+
+- Validate one or more addresses with FedEx.
+- Returns each resolved address plus its classification (e.g.
+- BUSINESS / RESIDENTIAL) and deliverability attributes.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | FedEx connected account |
+| `addresses` | object[] | yes |  |
+| `addresses[].postal_code` | string | yes |  |
+| `addresses[].country_code` | string | yes | ISO 3166-1 alpha-2 country code, e.g. VN, US, SG |
+| `addresses[].city` | string |  |  |
+| `addresses[].state_or_province_code` | string |  |  |
+| `addresses[].street_lines` | string[] |  |  |
+| `addresses[].residential` | boolean |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `resolved_addresses` | object[] | yes |  |
+| `resolved_addresses[].city` | string |  |  |
+| `resolved_addresses[].state_or_province_code` | string |  |  |
+| `resolved_addresses[].postal_code` | string |  |  |
+| `resolved_addresses[].country_code` | string |  |  |
+| `resolved_addresses[].classification` | string |  |  |
+| `resolved_addresses[].attributes` | object |  |  |
+
+## generate
+
+### generate_bank_qr_code (workflow step)
+
+- Generate a bank-payment QR code (VietQR for Vietnam) and save it as a PNG to the workspace.
+- The QR encodes the recipient bank, account number, and optional amount/description so any banking app can scan and pre-fill the transfer.
+- Call list_banks first to discover valid bank codes. (workflow step, chat)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `country` | "VN" | yes | Country whose bank-payment QR standard to use. Currently only 'VN' (Vietnam / VietQR) is supported. |
+| `bank_code` | "ICB" \\| "VCB" \\| "BIDV" \\| "VBA" \\| "OCB" \\| "MB" \\| "TCB" \\| "ACB" \\| "VPB" \\| "TPB" \\| "STB" \\| "HDB" \\| "VCCB" \\| "SCB" \\| "VIB" \\| "SHB" \\| "EIB" \\| "MSB" \\| "CAKE" \\| "Ubank" \\| "TIMO" \\| "SGICB" \\| "BAB" \\| "momo" \\| "PVDB" \\| "PVCB" \\| "MBV" \\| "NCB" \\| "SHBVN" \\| "ABB" \\| "VAB" \\| "NAB" \\| "PGB" \\| "VIETBANK" \\| "BVB" \\| "SEAB" \\| "COOPBANK" \\| "LPB" \\| "KLB" \\| "KBank" \\| "CIMB" \\| "WVN" | yes | Bank code from list_banks. Must belong to the specified country. (workflow step, chat) |
+| `account_number` | string | yes | Beneficiary account number at the bank. |
+| `amount` | number |  | Payment amount in the local currency (VND for Vietnam). Omit for a static QR with no fixed amount. |
+| `description` | string |  | Transfer description / memo. Max 50 bytes; Vietnamese diacritics use 2–3 bytes per character. |
+| `account_name` | string |  | Beneficiary name shown on the payer's banking app confirmation screen. Max 25 bytes — banks normalize Vietnamese names to ASCII uppercase, pass the normalized form (e.g. 'NGUYEN VAN A'). |
+| `filename` | string |  | Output filename. Defaults to 'bank_qr_<bank_code>.png'. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `id` | string | yes |  |
+| `filename` | string | yes |  |
+| `mime_type` | string | yes |  |
+| `url` | string | yes |  |
+| `bank` | object | yes |  |
+| `bank.country` | string | yes |  |
+| `bank.code` | string | yes |  |
+| `bank.short_name` | string | yes |  |
+| `bank.full_name` | string | yes |  |
+
+### generate_image (workflow step)
+
+- Generate an image from a text prompt and save it to the workspace.
+- Returns a file_id usable as an image field value or attachment.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `prompt` | string | yes | Description of the image to generate. |
+| `size` | "1024x1024" \\| "1024x1536" \\| "1536x1024" |  | Square, portrait, or landscape. |
+| `quality` | "low" \\| "medium" \\| "high" |  | Higher quality costs more. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `url` | string | yes |  |
+| `width` | number | yes |  |
+| `height` | number | yes |  |
+| `mime_type` | string | yes |  |
+
+### generate_qr_code (workflow step)
+
+- Generate a QR code PNG from text or a URL and save it to the workspace.
+- For bank payment QR codes, use generate_bank_qr_code instead — it builds the correct EMVCo payload from a bank code and account number. (workflow step, chat)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `data` | string | yes | Text or URL to encode into the QR code. |
+| `filename` | string |  | Output filename. Defaults to 'qr_code.png'. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `id` | string | yes |  |
+| `filename` | string | yes |  |
+| `mime_type` | string | yes |  |
+| `url` | string | yes |  |
+
+## gmail
+
+### gmail_get_thread (workflow step)
+
+- Retrieve all messages in a Gmail thread.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The ID of the connected Gmail account to use |
+| `thread_id` | string | yes | Gmail thread ID |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `messages` | object[] | yes |  |
+| `messages[].id` | string | yes | Gmail message ID |
+| `messages[].threadId` | string | yes | Gmail thread ID |
+| `messages[].labelIds` | string[] | yes | Gmail label IDs (e.g. INBOX, UNREAD) |
+| `messages[].subject` | string | yes | Email subject |
+| `messages[].from` | string | yes | Sender email address |
+| `messages[].to` | string | yes | Recipient email address |
+| `messages[].date` | string | yes | Email date in the workspace timezone, with its offset |
+| `messages[].snippet` | string | yes | Short plain-text preview of the email body |
+| `messages[].cc` | string \\| null |  | CC recipients |
+| `messages[].bcc` | string \\| null |  | BCC recipients |
+
+### gmail_query_emails (workflow step)
+
+- Search Gmail messages using Gmail search syntax. ## Query syntax Operators (no space after colon): - People: from:, to:, cc:, bcc:, deliveredto: - Content: subject:, "exact phrase", +exact_word, AROUND N (proximity) - Status: is:unread, is:read, is:starred, is:important, is:muted - Labels: label:name, in:inbox, in:sent, in:drafts, in:spam, in:trash, in:anywhere - Category: category:primary, category:social, category:promotions, category:updates, category:forums - Attachments: has:attachment, has:drive, filename:pdf, filename:report.xlsx (has:attachment matches non-inline attachments only — it misses inline-embedded PDFs, common in receipts/invoices; open the message with gmail_read_email to detect those) - Size: larger:5M, smaller:2M, size:1000000 - Dates (YYYY/MM/DD): after:2024/01/01, before:2024/12/31 - Relative dates: newer_than:7d, older_than:3m, newer_than:1y (d=days, m=months, y=years) Combining: space = AND, OR (uppercase), - (exclude), () for grouping, {} alternative OR syntax. (workflow step, chat)
+- Examples: - from:alice is:unread has:attachment - subject:"quarterly review" newer_than:2d - {from:alice from:bob} subject:project -in:drafts - larger:5M filename:pdf older_than:6m - in:anywhere deliveredto:billing@company.com
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The ID of the connected Gmail account to use |
+| `query` | string | yes | Gmail search syntax expression |
+| `max_result` | number | yes | Maximum number of emails to retrieve (1-50) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `messages` | object[] | yes | List of matching Gmail messages |
+| `messages[].id` | string | yes | Gmail message ID |
+| `messages[].threadId` | string | yes | Gmail thread ID |
+| `messages[].labelIds` | string[] | yes | Gmail label IDs (e.g. INBOX, UNREAD) |
+| `messages[].subject` | string | yes | Email subject |
+| `messages[].from` | string | yes | Sender email address |
+| `messages[].to` | string | yes | Recipient email address |
+| `messages[].date` | string | yes | Email date in the workspace timezone, with its offset |
+| `messages[].snippet` | string | yes | Short plain-text preview of the email body |
+| `messages[].cc` | string \\| null |  | CC recipients |
+| `messages[].bcc` | string \\| null |  | BCC recipients |
+
+### gmail_query_labels (workflow step)
+
+- List Gmail labels with message and thread counts.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The ID of the connected Gmail account to use |
+| `name` | string |  | Match labels by name prefix. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `labels` | object[] | yes |  |
+| `labels[].id` | string | yes |  |
+| `labels[].name` | string | yes |  |
+| `labels[].type` | string | yes | system or user |
+| `labels[].messagesTotal` | number | yes |  |
+| `labels[].messagesUnread` | number | yes |  |
+| `labels[].threadsTotal` | number | yes |  |
+| `labels[].threadsUnread` | number | yes |  |
+
+### gmail_read_email (workflow step)
+
+- Fetch a Gmail message's body and the list of its attachments.
+- Attachments are stored as workspace files — the result names each one's file_id; read one with view_files, attach one to a record with update_records. (workflow step, chat)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The ID of the connected account |
+| `message_id` | string | yes | The ID of the Gmail message to retrieve |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message` | object | yes | The full Gmail message |
+| `message.id` | string |  | Gmail message ID |
+| `message.threadId` | string |  | Gmail thread ID |
+| `message.historyId` | string |  | Gmail history ID |
+| `message.labelIds` | string[] |  | Gmail label IDs |
+| `message.subject` | string | yes | Email subject |
+| `message.from` | string | yes | Sender email address |
+| `message.to` | string | yes | Recipient email address |
+| `message.date` | string | yes | Email date in the workspace timezone, with its offset |
+| `message.body` | object | yes | Email body |
+| `message.body.type` | "text" \\| "html" | yes | Body content type |
+| `message.body.content` | string | yes | Body content |
+| `message.cc` | string \\| null |  | CC recipients |
+| `message.bcc` | string \\| null |  | BCC recipients |
+| `message.inReplyTo` | string \\| null |  | In-Reply-To header |
+| `message.replyTo` | string \\| null |  | Reply-To header |
+| `message.references` | string[] \\| null |  | References header |
+| `message.attachments` | object[] | yes | Email attachments |
+| `message.attachments[].partId` | string | yes | MIME part ID |
+| `message.attachments[].filename` | string | yes | Attachment filename as stored, which may differ from the sender's |
+| `message.attachments[].mimeType` | string | yes | MIME type as stored, recovered from the filename when the sender declared a generic one |
+| `message.attachments[].attachmentId` | string | yes | Gmail attachment ID |
+| `message.attachments[].file_id` | string |  | Stored file ID — pass to view_files to read it, or to update_records to attach it (workflow step, chat) |
+| `message.attachments[].size` | number |  | Stored size in bytes |
+
+### gmail_reply_email (workflow step)
+
+- Draft or send a reply to a Gmail message.
+- Use reply_body (markdown) or template_id + template_data — not both.
+- Attach stored files by passing their file_ids.
+- Leaves an unsent draft unless draft is false.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `original_message_id` | string | yes |  |
+| `reply_body` | string |  | Reply body (markdown). Mutually exclusive with template_id. |
+| `template_id` | string |  |  |
+| `template_data` | object |  |  |
+| `cc` | string |  | CC recipients, comma-separated |
+| `bcc` | string |  | BCC recipients, comma-separated |
+| `draft` | boolean |  | Leave true to save an unsent draft the member reviews. Pass false only to deliver the message now — delivery is irreversible. |
+| `file_ids` | string[] | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message_id` | string | yes | The ID of the sent message or saved draft |
+| `subject` | string | yes | The subject as sent |
+| `html` | string | yes | The body as sent, rendered to HTML |
+| `markdown` | string |  | The body as written in markdown; absent when a template rendered it |
+| `to` | string | yes | The original sender the reply went to |
+
+### gmail_send_email (workflow step)
+
+- Draft or send a Gmail email.
+- Use content (markdown) or template_id + template_data — not both.
+- Attach stored files by passing their file_ids.
+- Leaves an unsent draft unless draft is false.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `to` | string |  | Recipient email(s), comma-separated. Required unless using a template. |
+| `subject` | string |  |  |
+| `cc` | string |  | CC recipients, comma-separated |
+| `bcc` | string |  | BCC recipients, comma-separated |
+| `content` | string |  | Email body (markdown). Mutually exclusive with template_id. |
+| `template_id` | string |  |  |
+| `template_data` | object |  |  |
+| `draft` | boolean |  | Leave true to save an unsent draft the member reviews. Pass false only to deliver the message now — delivery is irreversible. |
+| `file_ids` | string[] | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message_id` | string | yes | The ID of the sent message or saved draft |
+| `subject` | string | yes | The subject as sent |
+| `html` | string | yes | The body as sent, rendered to HTML |
+| `markdown` | string |  | The body as written in markdown; absent when a template rendered it |
+| `to` | string | yes | The recipients as sent, comma-separated |
+
+## instagram
+
+### instagram_create_post (workflow step)
+
+- Publish to the connected Instagram account.
+- Instagram has no text-only posts.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `caption` | string | yes |  |
+| `media_file_ids` | string[] | yes | One image, one video (published as a reel), or 2–10 images and videos as a carousel. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `post_id` | string | yes |  |
+| `url` | string | yes |  |
+
+## kiotviet
+
+### kiotviet_cancel_invoice (workflow step)
+
+- Cancel a KiotViet sales invoice by id, returning its stock.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number | yes |  |
+| `void_payment` | boolean |  | Also void payments recorded on the invoice |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `cancelled` | true | yes |  |
+
+### kiotviet_cancel_order (workflow step)
+
+- Cancel a KiotViet sales order by id, releasing the stock it reserved.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number | yes |  |
+| `void_payment` | boolean |  | Also void payments recorded on the order |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `cancelled` | true | yes |  |
+
+### kiotviet_create_category (workflow step)
+
+- Create a KiotViet product group (nhóm hàng), optionally under a parent group.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `name` | string | yes |  |
+| `parent_id` | number |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `category` | object | yes |  |
+
+### kiotviet_create_customer (workflow step)
+
+- Create a KiotViet customer (khách hàng).
+- Returns the customer as KiotViet stores it, with its id and code.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `name` | string | yes |  |
+| `code` | string |  | Customer code (mã khách hàng) |
+| `contact_number` | string |  |  |
+| `email` | string |  |  |
+| `address` | string |  |  |
+| `location_name` | string |  | Province/district as KiotViet names it |
+| `ward_name` | string |  |  |
+| `gender` | boolean |  | true for male, false for female |
+| `birth_date` | string |  | yyyy-mm-dd |
+| `group_ids` | number[] |  | Customer group ids |
+| `comments` | string |  |  |
+| `branch_id` | number |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `customer` | object | yes |  |
+
+### kiotviet_create_invoice (workflow step)
+
+- Create a KiotViet sales invoice (hóa đơn), which deducts stock.
+- Pass order_id to invoice an existing order.
+- Returns the invoice as KiotViet stores it, with its id and code.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `branch_id` | number | yes |  |
+| `customer_id` | number |  |  |
+| `sold_by_id` | number | yes | KiotViet user id of the seller |
+| `purchase_date` | string |  | ISO datetime |
+| `description` | string |  |  |
+| `discount` | number |  | Discount amount on the whole document |
+| `lines` | object[] | yes |  |
+| `lines[].product_id` | number | yes |  |
+| `lines[].quantity` | number | yes |  |
+| `lines[].price` | number |  | Unit price |
+| `lines[].discount` | number |  | Discount amount on the line |
+| `lines[].note` | string |  |  |
+| `order_id` | number |  | The sales order this invoice settles |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `invoice` | object | yes |  |
+
+### kiotviet_create_order (workflow step)
+
+- Create a KiotViet sales order (đặt hàng) — the pre-invoice stage, which reserves stock.
+- Returns the order as KiotViet stores it, with its id and code.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `branch_id` | number | yes |  |
+| `customer_id` | number |  |  |
+| `sold_by_id` | number |  | KiotViet user id of the seller |
+| `purchase_date` | string |  | ISO datetime |
+| `description` | string |  |  |
+| `discount` | number |  | Discount amount on the whole document |
+| `lines` | object[] | yes |  |
+| `lines[].product_id` | number | yes |  |
+| `lines[].quantity` | number | yes |  |
+| `lines[].price` | number |  | Unit price |
+| `lines[].discount` | number |  | Discount amount on the line |
+| `lines[].note` | string |  |  |
+| `make_invoice` | boolean |  | Also issue the invoice at once |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `order` | object | yes |  |
+
+### kiotviet_create_product (workflow step)
+
+- Create a KiotViet product (hàng hóa), optionally with opening stock per branch.
+- Returns the product as KiotViet stores it, with its id and code.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `name` | string | yes |  |
+| `code` | string |  | Product code (mã hàng) |
+| `category_id` | number | yes | Product group id |
+| `base_price` | number |  | Selling price |
+| `unit` | string |  |  |
+| `allows_sale` | boolean |  |  |
+| `is_active` | boolean |  |  |
+| `description` | string |  |  |
+| `weight` | number |  | Grams |
+| `inventories` | object[] |  | Stock per branch |
+| `inventories[].branch_id` | number | yes |  |
+| `inventories[].on_hand` | number | yes |  |
+| `inventories[].cost` | number |  | Unit cost at this branch |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `product` | object | yes |  |
+
+### kiotviet_delete_product (workflow step)
+
+- Delete a KiotViet product by id.
+- KiotViet refuses one that already appears on invoices.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `deleted` | true | yes |  |
+
+### kiotviet_get_customer (workflow step)
+
+- Get one KiotViet customer by id or by customer code (mã khách hàng).
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number |  |  |
+| `code` | string |  | Customer code (mã khách hàng), e.g. KH000123 |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `customer` | object | yes |  |
+
+### kiotviet_get_invoice (workflow step)
+
+- Get one KiotViet sales invoice by id or by invoice code (mã hóa đơn), with its line items and payments.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number |  |  |
+| `code` | string |  | Invoice code (mã hóa đơn), e.g. HD000123 |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `invoice` | object | yes |  |
+
+### kiotviet_get_product (workflow step)
+
+- Get one KiotViet product by id or by product code (mã hàng), with stock per branch in inventories[].
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number |  |  |
+| `code` | string |  | Product code (mã hàng), e.g. SP000123 |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `product` | object | yes |  |
+
+### kiotviet_list_branches (workflow step)
+
+- List the store's KiotViet branches (chi nhánh).
+- Branch ids scope inventory, invoices and orders.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `page_size` | number |  | Rows per page, up to 100 |
+| `current_item` | number |  | Zero-based offset of the first row |
+| `last_modified_from` | string |  | ISO datetime; only rows modified at or after it |
+| `include_removed_ids` | boolean |  | Also return removed_ids — rows deleted since last_modified_from |
+| `order_by` | string |  | KiotViet field name to sort by |
+| `order_direction` | "Asc" \\| "Desc" |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `total` | number |  | Rows matching the query across all pages |
+| `page_size` | number |  |  |
+| `items` | object[] | yes | Rows as KiotViet returns them |
+| `removed_ids` | number[] |  |  |
+
+### kiotviet_list_categories (workflow step)
+
+- List KiotViet product groups (nhóm hàng).
+- Each row carries its parentId, so the tree can be rebuilt from the flat list.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `page_size` | number |  | Rows per page, up to 100 |
+| `current_item` | number |  | Zero-based offset of the first row |
+| `last_modified_from` | string |  | ISO datetime; only rows modified at or after it |
+| `include_removed_ids` | boolean |  | Also return removed_ids — rows deleted since last_modified_from |
+| `order_by` | string |  | KiotViet field name to sort by |
+| `order_direction` | "Asc" \\| "Desc" |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `total` | number |  | Rows matching the query across all pages |
+| `page_size` | number |  |  |
+| `items` | object[] | yes | Rows as KiotViet returns them |
+| `removed_ids` | number[] |  |  |
+
+### kiotviet_list_customers (workflow step)
+
+- List KiotViet customers (khách hàng) with their lifetime totals — totalInvoiced, totalRevenue, debt, totalPoint.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `page_size` | number |  | Rows per page, up to 100 |
+| `current_item` | number |  | Zero-based offset of the first row |
+| `last_modified_from` | string |  | ISO datetime; only rows modified at or after it |
+| `include_removed_ids` | boolean |  | Also return removed_ids — rows deleted since last_modified_from |
+| `order_by` | string |  | KiotViet field name to sort by |
+| `order_direction` | "Asc" \\| "Desc" |  |  |
+| `code` | string |  | Customer code (mã khách hàng) |
+| `name` | string |  | Name search |
+| `contact_number` | string |  | Phone number |
+| `group_id` | number |  | Only customers in this customer group |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `total` | number |  | Rows matching the query across all pages |
+| `page_size` | number |  |  |
+| `items` | object[] | yes | Rows as KiotViet returns them |
+| `removed_ids` | number[] |  |  |
+
+### kiotviet_list_invoices (workflow step)
+
+- List KiotViet sales invoices (hóa đơn) with their line items in invoiceDetails[] — productCode, productName, quantity, price, discount, subTotal.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `page_size` | number |  | Rows per page, up to 100 |
+| `current_item` | number |  | Zero-based offset of the first row |
+| `last_modified_from` | string |  | ISO datetime; only rows modified at or after it |
+| `include_removed_ids` | boolean |  | Also return removed_ids — rows deleted since last_modified_from |
+| `order_by` | string |  | KiotViet field name to sort by |
+| `order_direction` | "Asc" \\| "Desc" |  |  |
+| `branch_ids` | number[] |  |  |
+| `customer_ids` | number[] |  |  |
+| `customer_code` | string |  | Customer code (mã khách hàng) |
+| `status` | number[] |  | KiotViet status codes; each row carries statusValue with the label |
+| `from_purchase_date` | string |  | Date, yyyy-mm-dd |
+| `to_purchase_date` | string |  | Date, yyyy-mm-dd |
+| `include_payment` | boolean |  | Include payments[] on each row |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `total` | number |  | Rows matching the query across all pages |
+| `page_size` | number |  |  |
+| `items` | object[] | yes | Rows as KiotViet returns them |
+| `removed_ids` | number[] |  |  |
+
+### kiotviet_list_orders (workflow step)
+
+- List KiotViet sales orders (đặt hàng) — the pre-invoice stage — with line items in orderDetails[].
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `page_size` | number |  | Rows per page, up to 100 |
+| `current_item` | number |  | Zero-based offset of the first row |
+| `last_modified_from` | string |  | ISO datetime; only rows modified at or after it |
+| `include_removed_ids` | boolean |  | Also return removed_ids — rows deleted since last_modified_from |
+| `order_by` | string |  | KiotViet field name to sort by |
+| `order_direction` | "Asc" \\| "Desc" |  |  |
+| `branch_ids` | number[] |  |  |
+| `customer_ids` | number[] |  |  |
+| `customer_code` | string |  | Customer code (mã khách hàng) |
+| `status` | number[] |  | KiotViet status codes; each row carries statusValue with the label |
+| `from_purchase_date` | string |  | Date, yyyy-mm-dd |
+| `to_purchase_date` | string |  | Date, yyyy-mm-dd |
+| `include_payment` | boolean |  | Include payments[] on each row |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `total` | number |  | Rows matching the query across all pages |
+| `page_size` | number |  |  |
+| `items` | object[] | yes | Rows as KiotViet returns them |
+| `removed_ids` | number[] |  |  |
+
+### kiotviet_list_products (workflow step)
+
+- List KiotViet products (hàng hóa) with stock per branch.
+- Each row's inventories[] carries branchId, onHand (tồn kho), reserved (đặt hàng) and cost.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `page_size` | number |  | Rows per page, up to 100 |
+| `current_item` | number |  | Zero-based offset of the first row |
+| `last_modified_from` | string |  | ISO datetime; only rows modified at or after it |
+| `include_removed_ids` | boolean |  | Also return removed_ids — rows deleted since last_modified_from |
+| `order_by` | string |  | KiotViet field name to sort by |
+| `order_direction` | "Asc" \\| "Desc" |  |  |
+| `category_id` | number |  | Only products in this product group |
+| `is_active` | boolean |  | Only products still on sale (true) or discontinued (false) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `total` | number |  | Rows matching the query across all pages |
+| `page_size` | number |  |  |
+| `items` | object[] | yes | Rows as KiotViet returns them |
+| `removed_ids` | number[] |  |  |
+
+### kiotviet_list_purchase_orders (workflow step)
+
+- List KiotViet purchase orders (phiếu nhập hàng) — goods received from suppliers — with line items in purchaseOrderDetails[].
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `page_size` | number |  | Rows per page, up to 100 |
+| `current_item` | number |  | Zero-based offset of the first row |
+| `last_modified_from` | string |  | ISO datetime; only rows modified at or after it |
+| `include_removed_ids` | boolean |  | Also return removed_ids — rows deleted since last_modified_from |
+| `order_by` | string |  | KiotViet field name to sort by |
+| `order_direction` | "Asc" \\| "Desc" |  |  |
+| `branch_ids` | number[] |  |  |
+| `status` | number[] |  | KiotViet status codes; each row carries statusValue with the label |
+| `from_purchase_date` | string |  | Date, yyyy-mm-dd |
+| `to_purchase_date` | string |  | Date, yyyy-mm-dd |
+| `include_payment` | boolean |  | Include payments[] on each row |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `total` | number |  | Rows matching the query across all pages |
+| `page_size` | number |  |  |
+| `items` | object[] | yes | Rows as KiotViet returns them |
+| `removed_ids` | number[] |  |  |
+
+### kiotviet_update_category (workflow step)
+
+- Rename a KiotViet product group or move it under another parent.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number | yes |  |
+| `name` | string |  |  |
+| `parent_id` | number |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `category` | object | yes |  |
+
+### kiotviet_update_customer (workflow step)
+
+- Update a KiotViet customer by id.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number | yes |  |
+| `name` | string |  |  |
+| `code` | string |  | Customer code (mã khách hàng) |
+| `contact_number` | string |  |  |
+| `email` | string |  |  |
+| `address` | string |  |  |
+| `location_name` | string |  | Province/district as KiotViet names it |
+| `ward_name` | string |  |  |
+| `gender` | boolean |  | true for male, false for female |
+| `birth_date` | string |  | yyyy-mm-dd |
+| `group_ids` | number[] |  | Customer group ids |
+| `comments` | string |  |  |
+| `branch_id` | number |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `customer` | object | yes |  |
+
+### kiotviet_update_invoice (workflow step)
+
+- Update a KiotViet sales invoice by id.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number | yes |  |
+| `branch_id` | number |  |  |
+| `customer_id` | number |  |  |
+| `sold_by_id` | number |  | KiotViet user id of the seller |
+| `purchase_date` | string |  | ISO datetime |
+| `description` | string |  |  |
+| `discount` | number |  | Discount amount on the whole document |
+| `lines` | object[] |  |  |
+| `lines[].product_id` | number | yes |  |
+| `lines[].quantity` | number | yes |  |
+| `lines[].price` | number |  | Unit price |
+| `lines[].discount` | number |  | Discount amount on the line |
+| `lines[].note` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `invoice` | object | yes |  |
+
+### kiotviet_update_order (workflow step)
+
+- Update a KiotViet sales order by id.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number | yes |  |
+| `branch_id` | number |  |  |
+| `customer_id` | number |  |  |
+| `sold_by_id` | number |  | KiotViet user id of the seller |
+| `purchase_date` | string |  | ISO datetime |
+| `description` | string |  |  |
+| `discount` | number |  | Discount amount on the whole document |
+| `lines` | object[] |  |  |
+| `lines[].product_id` | number | yes |  |
+| `lines[].quantity` | number | yes |  |
+| `lines[].price` | number |  | Unit price |
+| `lines[].discount` | number |  | Discount amount on the line |
+| `lines[].note` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `order` | object | yes |  |
+
+### kiotviet_update_product (workflow step)
+
+- Update a KiotViet product by id; inventories set the stock level per branch.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | KiotViet connected account |
+| `id` | number | yes |  |
+| `name` | string |  |  |
+| `code` | string |  | Product code (mã hàng) |
+| `category_id` | number |  | Product group id |
+| `base_price` | number |  | Selling price |
+| `unit` | string |  |  |
+| `allows_sale` | boolean |  |  |
+| `is_active` | boolean |  |  |
+| `description` | string |  |  |
+| `weight` | number |  | Grams |
+| `inventories` | object[] |  | Stock per branch |
+| `inventories[].branch_id` | number | yes |  |
+| `inventories[].on_hand` | number | yes |  |
+| `inventories[].cost` | number |  | Unit cost at this branch |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `product` | object | yes |  |
+
+## lark
+
+### lark_create_records (workflow step)
+
+- Create one or many records in a Lark Base (Bitable) table (max 500 per call). fields are keyed by Lark field name.
+- Returns the new record ids.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Lark connected account |
+| `app_token` | string | yes | Lark Base app_token (the Base id) |
+| `table_id` | string | yes | Lark Bitable table id |
+| `records` | object[] | yes |  |
+| `records[].fields` | object | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `created` | number | yes |  |
+| `records` | object[] | yes |  |
+| `records[].record_id` | string | yes |  |
+| `records[].fields` | object | yes |  |
+
+### lark_delete_records (workflow step)
+
+- Delete one or many records from a Lark Base (Bitable) table by record_id (max 500 per call).
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Lark connected account |
+| `app_token` | string | yes | Lark Base app_token (the Base id) |
+| `table_id` | string | yes | Lark Bitable table id |
+| `record_ids` | string[] | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `deleted` | number | yes |  |
+| `record_ids` | string[] | yes |  |
+
+### lark_get_record (workflow step)
+
+- Get one record from a Lark Base (Bitable) table by its record_id.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Lark connected account |
+| `app_token` | string | yes | Lark Base app_token (the Base id) |
+| `table_id` | string | yes | Lark Bitable table id |
+| `record_id` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `record_id` | string | yes |  |
+| `fields` | object | yes |  |
+
+### lark_list_fields (workflow step)
+
+- List the fields (columns) of a Lark Base (Bitable) table — name, id, and type.
+- Use to discover the schema before reading or writing records.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Lark connected account |
+| `app_token` | string | yes | Lark Base app_token (the Base id) |
+| `table_id` | string | yes | Lark Bitable table id |
+| `page_size` | number |  |  |
+| `page_token` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `fields` | object[] | yes |  |
+| `fields[].field_id` | string |  |  |
+| `fields[].field_name` | string |  |  |
+| `fields[].type` | number |  |  |
+| `fields[].ui_type` | string |  |  |
+| `fields[].is_primary` | boolean |  |  |
+| `has_more` | boolean | yes |  |
+| `page_token` | string |  |  |
+
+### lark_list_records (workflow step)
+
+- List records from a Lark Base (Bitable) table.
+- Returns each record's id and fields (keyed by Lark field name).
+- Optionally narrow with filter / sort / field_names / view_id; paginate with page_token.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Lark connected account |
+| `app_token` | string | yes | Lark Base app_token (the Base id) |
+| `table_id` | string | yes | Lark Bitable table id |
+| `filter` | object |  |  |
+| `filter.conjunction` | "and" \\| "or" | yes |  |
+| `filter.conditions` | object[] | yes |  |
+| `filter.conditions[].field_name` | string | yes |  |
+| `filter.conditions[].operator` | string | yes | e.g. is, isNot, contains, isGreater, isEmpty |
+| `filter.conditions[].value` | string[] |  |  |
+| `sort` | object[] |  |  |
+| `sort[].field_name` | string | yes |  |
+| `sort[].desc` | boolean |  |  |
+| `field_names` | string[] |  | Restrict returned fields by name |
+| `view_id` | string |  |  |
+| `page_size` | number |  |  |
+| `page_token` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `records` | object[] | yes |  |
+| `records[].record_id` | string | yes |  |
+| `records[].fields` | object | yes |  |
+| `has_more` | boolean | yes |  |
+| `page_token` | string |  |  |
+| `total` | number |  |  |
+
+### lark_list_tables (workflow step)
+
+- List the tables in a Lark Base (Bitable) — id and name.
+- Use to discover which table_id to read or write.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Lark connected account |
+| `app_token` | string | yes | Lark Base app_token (the Base id) |
+| `page_size` | number |  |  |
+| `page_token` | string |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `tables` | object[] | yes |  |
+| `tables[].table_id` | string |  |  |
+| `tables[].name` | string |  |  |
+| `has_more` | boolean | yes |  |
+| `page_token` | string |  |  |
+
+### lark_update_records (workflow step)
+
+- Update one or many existing records in a Lark Base (Bitable) table by record_id (max 500 per call). fields are keyed by Lark field name; only provided fields change.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Lark connected account |
+| `app_token` | string | yes | Lark Base app_token (the Base id) |
+| `table_id` | string | yes | Lark Bitable table id |
+| `records` | object[] | yes |  |
+| `records[].record_id` | string | yes |  |
+| `records[].fields` | object | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `updated` | number | yes |  |
+| `records` | object[] | yes |  |
+| `records[].record_id` | string | yes |  |
+| `records[].fields` | object | yes |  |
+
+## linkedin
+
+### linkedin_create_post (workflow step)
+
+- Publish a post to the connected LinkedIn member's profile.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `text` | string | yes |  |
+| `link` | string |  | Shown as an article card; needs link_title. A post carries either a link or media. |
+| `link_title` | string |  |  |
+| `media_file_ids` | string[] |  | Up to 20 images, or one video. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `post_id` | string | yes |  |
+| `url` | string | yes |  |
+
+## list
+
+### list_banks (workflow step)
+
+- List banks supported by generate_bank_qr_code. (workflow step, chat)
+- Returns the bank code (used as input to the generator), display name, and country.
+- Call this before generate_bank_qr_code to discover valid codes. (workflow step, chat)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `country` | "VN" |  | Filter to banks from a specific country. Omit to list all supported banks. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `banks` | object[] | yes |  |
+| `banks[].country` | string | yes |  |
+| `banks[].code` | string | yes |  |
+| `banks[].bin` | string | yes |  |
+| `banks[].short_name` | string | yes |  |
+| `banks[].full_name` | string | yes |  |
+
+## lookup
+
+### lookup_business (workflow step)
+
+- Look up business registration info by tax / registration code.
+- Defaults to Vietnam (country='VN').
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `tax_code` | string | yes | Business tax / registration code. Format varies by country; for VN this is a 10–13 digit mã số thuế. |
+| `country` | string |  | ISO country code. Defaults to 'VN' (Vietnam). Only 'VN' is supported today. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `country` | string | yes |  |
+| `tax_code` | string | yes |  |
+| `name` | string | yes |  |
+| `address` | string | yes |  |
+| `representative` | string \\| null | yes |  |
+| `status` | string \\| null | yes |  |
+| `international_name` | string \\| null | yes |  |
+| `short_name` | string \\| null | yes |  |
+| `operating_since` | string \\| null | yes |  |
+| `managed_by` | string \\| null | yes |  |
+| `company_type` | string \\| null | yes |  |
+| `primary_industry` | string \\| null | yes |  |
+
+## misa
+
+### misa_get_dictionary (workflow step)
+
+- Read master-data records from MISA AMIS to look up codes (customer code, item code, warehouse code, etc.) before pushing a voucher.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | MISA connected account to read from |
+| `data_type` | 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| 8 \\| 9 \\| 10 \\| 11 \\| 12 | yes | 1 objects (customers/suppliers/employees), 2 inventory items, 3 stocks, 4 units, 5 chart of accounts, 6 organization units, 8 bank accounts, 9 projects, 10 cost objects, 11 payment terms, 12 banks |
+| `skip` | integer |  |  |
+| `take` | integer |  | Max 100 per page |
+| `last_sync_time` | string |  | ISO timestamp — only return records changed since this time |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `success` | boolean | yes |  |
+| `data` | any | yes | Raw dictionary records as returned by MISA |
+| `last_sync_time` | string |  | Cursor — pass as last_sync_time on the next call to fetch only newer changes |
+| `error_code` | string |  |  |
+| `error_message` | string |  |  |
+
+### misa_save_bank_voucher (workflow step)
+
+- Push a bank voucher (deposit / withdrawal / transfer) into MISA AMIS. voucher_type: 1 deposit (báo có), 3 withdrawal/debit-advice (báo nợ), 2 internal transfer. bank_account_id is the company-side bank account GUID — look it up with misa_get_dictionary (data_type 8). (workflow step)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `voucher_type` | 1 \\| 2 \\| 3 | yes |  |
+| `reftype` | integer |  |  |
+| `org_refid` | string | yes | Caller-controlled UUID identifying the source document |
+| `org_refno` | string |  | Source-system document number |
+| `refdate` | string | yes | Document date, ISO 8601 |
+| `posted_date` | string | yes | Accounting posting date, ISO 8601 |
+| `branch_id` | string |  | MISA branch GUID, optional for single-branch tenants |
+| `currency_id` | string |  | Currency code, default VND |
+| `exchange_rate` | number |  | FX rate, default 1.0 |
+| `journal_memo` | string |  | Voucher memo/notes |
+| `custom_field1` | string |  |  |
+| `custom_field2` | string |  |  |
+| `custom_field3` | string |  |  |
+| `custom_field4` | string |  |  |
+| `custom_field5` | string |  |  |
+| `bank_account_id` | string | yes | Bank account GUID in MISA — look up via misa_get_dictionary (workflow step) |
+| `account_object_code` | string |  |  |
+| `account_object_name` | string |  |  |
+| `total_amount_oc` | number | yes |  |
+| `total_amount` | number | yes |  |
+| `detail` | object[] | yes |  |
+| `detail[].description` | string | yes |  |
+| `detail[].amount_oc` | number | yes |  |
+| `detail[].amount` | number | yes |  |
+| `detail[].debit_account` | string | yes |  |
+| `detail[].credit_account` | string | yes |  |
+| `detail[].sort_order` | integer |  |  |
+| `connected_account_id` | string | yes | MISA connected account to push to |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `queued` | boolean | yes |  |
+| `org_refid` | string | yes |  |
+| `error_code` | string |  |  |
+| `error_message` | string |  |  |
+
+### misa_save_cash_voucher (workflow step)
+
+- Push a cash voucher (cash receipt or cash payment) into MISA AMIS. voucher_type: 5 receipt (thu tiền), 4 payment (chi tiền). detail array carries the journal lines with debit_account/credit_account per Vietnamese chart-of-accounts.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `voucher_type` | 4 \\| 5 | yes |  |
+| `reftype` | integer |  |  |
+| `org_refid` | string | yes | Caller-controlled UUID identifying the source document |
+| `org_refno` | string |  | Source-system document number |
+| `refdate` | string | yes | Document date, ISO 8601 |
+| `posted_date` | string | yes | Accounting posting date, ISO 8601 |
+| `branch_id` | string |  | MISA branch GUID, optional for single-branch tenants |
+| `currency_id` | string |  | Currency code, default VND |
+| `exchange_rate` | number |  | FX rate, default 1.0 |
+| `journal_memo` | string |  | Voucher memo/notes |
+| `custom_field1` | string |  |  |
+| `custom_field2` | string |  |  |
+| `custom_field3` | string |  |  |
+| `custom_field4` | string |  |  |
+| `custom_field5` | string |  |  |
+| `account_object_code` | string |  | Counterparty code (customer/supplier/employee) |
+| `account_object_name` | string |  |  |
+| `total_amount_oc` | number | yes |  |
+| `total_amount` | number | yes |  |
+| `detail` | object[] | yes |  |
+| `detail[].description` | string | yes |  |
+| `detail[].amount_oc` | number | yes |  |
+| `detail[].amount` | number | yes |  |
+| `detail[].debit_account` | string | yes |  |
+| `detail[].credit_account` | string | yes |  |
+| `detail[].sort_order` | integer |  |  |
+| `connected_account_id` | string | yes | MISA connected account to push to |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `queued` | boolean | yes |  |
+| `org_refid` | string | yes |  |
+| `error_code` | string |  |  |
+| `error_message` | string |  |  |
+
+### misa_save_dictionary (workflow step)
+
+- Create or update master-data records in MISA AMIS (customers, suppliers, items, warehouses, etc.).
+- Use this before pushing a voucher that references a code MISA doesn't yet know about.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | MISA connected account to push to |
+| `dictionary_type` | 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| 7 \\| 8 \\| 9 \\| 10 \\| 12 | yes | 1 customers/suppliers/employees, 2 object groups, 3 inventory items, 4 item categories, 5 warehouses, 6 units, 7 bank accounts, 8 banks, 9 expense items, 10 revenue/expense categories, 12 cost allocation |
+| `items` | object[] | yes | Master-data records to create or update. 1–200 per call. Each item's required fields depend on dictionary_type — see MISA Open API docs (chat, MCP, CLI) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `queued` | boolean | yes |  |
+| `count` | integer | yes |  |
+| `error_code` | string |  |  |
+| `error_message` | string |  |  |
+
+### misa_save_purchase_voucher (workflow step)
+
+- Push a purchase voucher (purchase invoice / return / discount-debit-note-to-supplier / service / general purchase / purchase order) into MISA AMIS. voucher_type: 15 invoice, 18 voucher, 17 service, 16 return, 14 discount (debit note to supplier), 21 purchase order. account_object_code identifies the supplier in MISA — must already exist.
+- MISA sync ack only confirms queueing; final accept/reject arrives async.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `voucher_type` | 14 \\| 15 \\| 16 \\| 17 \\| 18 \\| 21 | yes |  |
+| `reftype` | integer |  |  |
+| `org_refid` | string | yes | Caller-controlled UUID identifying the source document |
+| `org_refno` | string |  | Source-system document number |
+| `refdate` | string | yes | Document date, ISO 8601 |
+| `posted_date` | string | yes | Accounting posting date, ISO 8601 |
+| `branch_id` | string |  | MISA branch GUID, optional for single-branch tenants |
+| `currency_id` | string |  | Currency code, default VND |
+| `exchange_rate` | number |  | FX rate, default 1.0 |
+| `journal_memo` | string |  | Voucher memo/notes |
+| `custom_field1` | string |  |  |
+| `custom_field2` | string |  |  |
+| `custom_field3` | string |  |  |
+| `custom_field4` | string |  |  |
+| `custom_field5` | string |  |  |
+| `account_object_code` | string | yes | Supplier code in MISA |
+| `account_object_name` | string |  |  |
+| `account_object_tax_code` | string |  |  |
+| `account_object_address` | string |  |  |
+| `total_amount_oc` | number | yes |  |
+| `total_amount` | number | yes |  |
+| `total_vat_amount_oc` | number | yes |  |
+| `total_vat_amount` | number | yes |  |
+| `detail` | object[] | yes |  |
+| `detail[].inventory_item_code` | string |  | Item/product code in MISA. Skip when is_description=true |
+| `detail[].inventory_item_name` | string | yes | Item/product display name |
+| `detail[].inventory_item_type` | 0 \\| 1 \\| 2 \\| 3 |  | Item type — 0 goods, 1 finished, 2 service, 3 raw material |
+| `detail[].description` | string |  | Line description |
+| `detail[].is_description` | boolean |  | Description-only line — when true, only `description` is required |
+| `detail[].stock_code` | string |  | Warehouse code in MISA |
+| `detail[].unit_name` | string |  | Unit of measure name |
+| `detail[].quantity` | number | yes | Line quantity |
+| `detail[].unit_price` | number | yes | Unit price (in currency_id of voucher) |
+| `detail[].amount_oc` | number | yes | Line total in original currency |
+| `detail[].amount` | number | yes | Line total in accounting currency (= amount_oc when VND) |
+| `detail[].discount_rate` | number |  | Line discount percent |
+| `detail[].discount_amount_oc` | number |  | Discount amount, original currency |
+| `detail[].discount_amount` | number |  | Discount amount, accounting currency |
+| `detail[].vat_rate` | number | yes | VAT percent. 0/5/8/10 for standard, -1 exempt, -2 not creditable, -3 other (set other_vat_rate) |
+| `detail[].other_vat_rate` | number |  | Custom VAT percent — required when vat_rate=-3 |
+| `detail[].vat_amount_oc` | number | yes | VAT amount, original currency |
+| `detail[].vat_amount` | number | yes | VAT amount, accounting currency |
+| `detail[].debit_account` | string | yes | Chart-of-accounts code on debit side, e.g. 131 |
+| `detail[].credit_account` | string | yes | Chart-of-accounts code on credit side, e.g. 511 |
+| `detail[].sale_account` | string |  |  |
+| `detail[].vat_account` | string |  |  |
+| `detail[].inventory_account` | string |  |  |
+| `detail[].sort_order` | integer |  |  |
+| `detail[].lot_no` | string |  |  |
+| `detail[].expiry_date` | string |  | ISO date |
+| `detail[].organization_unit_code` | string |  | Department/branch code |
+| `connected_account_id` | string | yes | MISA connected account to push to |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `queued` | boolean | yes |  |
+| `org_refid` | string | yes |  |
+| `error_code` | string |  |  |
+| `error_message` | string |  |  |
+
+### misa_save_sales_voucher (workflow step)
+
+- Push a sales voucher (invoice / sales return / discount-credit-note / sales order) into MISA AMIS. voucher_type: 11 invoice, 13 sales voucher, 12 return, 10 discount/credit note, 20 sales order. reftype refines the sub-type (e.g. 3530 unpaid sale, 3560 sales invoice, 3571 service cash). account_object_code identifies the customer in MISA — must already exist (use misa_save_dictionary first if not). (workflow step)
+- MISA sync ack only confirms queueing; final accept/reject arrives async on the registered callback URL.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `voucher_type` | 10 \\| 11 \\| 12 \\| 13 \\| 20 | yes |  |
+| `reftype` | integer |  | Voucher sub-type code — MISA assigns a default when omitted |
+| `org_refid` | string | yes | Caller-controlled UUID identifying the source document |
+| `org_refno` | string |  | Source-system document number |
+| `refdate` | string | yes | Document date, ISO 8601 |
+| `posted_date` | string | yes | Accounting posting date, ISO 8601 |
+| `branch_id` | string |  | MISA branch GUID, optional for single-branch tenants |
+| `currency_id` | string |  | Currency code, default VND |
+| `exchange_rate` | number |  | FX rate, default 1.0 |
+| `journal_memo` | string |  | Voucher memo/notes |
+| `custom_field1` | string |  |  |
+| `custom_field2` | string |  |  |
+| `custom_field3` | string |  |  |
+| `custom_field4` | string |  |  |
+| `custom_field5` | string |  |  |
+| `account_object_code` | string | yes | Customer code in MISA |
+| `account_object_name` | string |  |  |
+| `account_object_tax_code` | string |  |  |
+| `account_object_address` | string |  |  |
+| `employee_code` | string |  | Salesperson code |
+| `employee_name` | string |  |  |
+| `total_sale_amount_oc` | number | yes |  |
+| `total_sale_amount` | number | yes |  |
+| `total_discount_amount_oc` | number |  |  |
+| `total_discount_amount` | number |  |  |
+| `total_vat_amount_oc` | number | yes |  |
+| `total_vat_amount` | number | yes |  |
+| `total_amount_oc` | number | yes |  |
+| `total_amount` | number | yes |  |
+| `is_sale_with_outward` | boolean |  | Auto-generate stock-out slip |
+| `detail` | object[] | yes |  |
+| `detail[].inventory_item_code` | string |  | Item/product code in MISA. Skip when is_description=true |
+| `detail[].inventory_item_name` | string | yes | Item/product display name |
+| `detail[].inventory_item_type` | 0 \\| 1 \\| 2 \\| 3 |  | Item type — 0 goods, 1 finished, 2 service, 3 raw material |
+| `detail[].description` | string |  | Line description |
+| `detail[].is_description` | boolean |  | Description-only line — when true, only `description` is required |
+| `detail[].stock_code` | string |  | Warehouse code in MISA |
+| `detail[].unit_name` | string |  | Unit of measure name |
+| `detail[].quantity` | number | yes | Line quantity |
+| `detail[].unit_price` | number | yes | Unit price (in currency_id of voucher) |
+| `detail[].amount_oc` | number | yes | Line total in original currency |
+| `detail[].amount` | number | yes | Line total in accounting currency (= amount_oc when VND) |
+| `detail[].discount_rate` | number |  | Line discount percent |
+| `detail[].discount_amount_oc` | number |  | Discount amount, original currency |
+| `detail[].discount_amount` | number |  | Discount amount, accounting currency |
+| `detail[].vat_rate` | number | yes | VAT percent. 0/5/8/10 for standard, -1 exempt, -2 not creditable, -3 other (set other_vat_rate) |
+| `detail[].other_vat_rate` | number |  | Custom VAT percent — required when vat_rate=-3 |
+| `detail[].vat_amount_oc` | number | yes | VAT amount, original currency |
+| `detail[].vat_amount` | number | yes | VAT amount, accounting currency |
+| `detail[].debit_account` | string | yes | Chart-of-accounts code on debit side, e.g. 131 |
+| `detail[].credit_account` | string | yes | Chart-of-accounts code on credit side, e.g. 511 |
+| `detail[].sale_account` | string |  |  |
+| `detail[].vat_account` | string |  |  |
+| `detail[].inventory_account` | string |  |  |
+| `detail[].sort_order` | integer |  |  |
+| `detail[].lot_no` | string |  |  |
+| `detail[].expiry_date` | string |  | ISO date |
+| `detail[].organization_unit_code` | string |  | Department/branch code |
+| `connected_account_id` | string | yes | MISA connected account to push to |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `queued` | boolean | yes |  |
+| `org_refid` | string | yes |  |
+| `error_code` | string |  |  |
+| `error_message` | string |  |  |
+
+## outlook
+
+### outlook_count_emails (workflow step)
+
+- Count Outlook emails matching a filter or search query.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |
+| `search` | string |  | KQL expression |
+| `filter` | string |  | OData expression |
+| `folder` | string |  | Mail folder: well-known name or folder ID |
+| `user_id` | string |  | Mailbox owner user ID. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `count` | number | yes | Number of matching emails |
+
+### outlook_query_emails (workflow step)
+
+- Search and filter Outlook emails.
+- Two modes: search (KQL keywords) or structured filters (from, to, subject, dates, etc.).
+- When search is provided, structured filters are ignored. ## KQL search syntax (for the search field) Bare keywords search across from, subject, and body.
+- Property restrictions (no space after colon): - People: from:, to:, cc:, bcc:, participants: (all people fields), recipients: (to+cc+bcc) - Content: subject:, body:, "exact phrase" - Attachments: hasAttachments:true, attachment:filename* - Dates: received:2024-01-01, received:2024-01-01..2024-01-31, received>=2024-01-01, received:today, received:"this week", sent:2024-06-01 - Size (bytes): size>1048576, size:1..10485760 - Status: importance:high, isRead:false, kind:email Combining (UPPERCASE required): AND, OR, NOT, - (exclude), () for grouping.
+- Prefix wildcard: subject:set* (end of word only, no *prefix or *mid*dle).
+- Examples: - from:john@contoso.com AND subject:"quarterly report" - participants:alice importance:high hasAttachments:true - body:contract AND received>=2024-01-01 AND received<=2024-06-30 - (from:legal OR from:compliance) AND subject:contract - attachment:annual* received:"this month"
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |
+| `search` | string |  | KQL search query — overrides all structured filter fields when provided |
+| `from` | string |  | Sender email address exact match |
+| `to` | string |  | Recipient email address exact match |
+| `subject` | string |  | Subject starts with this text |
+| `after` | string |  | ISO date — received on or after |
+| `before` | string |  | ISO date — received before |
+| `is_read` | boolean |  |  |
+| `is_draft` | boolean |  |  |
+| `has_attachments` | boolean |  |  |
+| `importance` | "low" \\| "normal" \\| "high" |  |  |
+| `is_flagged` | boolean |  | Whether the email is flagged for follow-up |
+| `classification` | "focused" \\| "other" |  | Focused Inbox classification |
+| `category` | string |  | Color category name |
+| `conversation_id` | string |  | Outlook conversation ID — retrieves all messages in a thread |
+| `folder` | string |  | Mail folder: well-known name (inbox, sentitems, drafts, deleteditems, junkemail, archive) or folder ID |
+| `skip` | number |  | Number of results to skip for pagination. |
+| `max_result` | number | yes | Maximum number of emails to retrieve (1-50) |
+| `user_id` | string |  | The ID of the user whose mailbox the email belongs to. If not provided, the connected account's user ID (me) will be used. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `messages` | object[] | yes | List of matching Outlook messages |
+| `messages[].id` | string | yes | Outlook message ID |
+| `messages[].date` | string | yes | Email date in the workspace timezone, with its offset |
+| `messages[].from` | string | yes | Sender email address |
+| `messages[].subject` | string | yes | Email subject |
+| `messages[].to` | string | yes | Recipient email address |
+| `messages[].cc` | string \\| null | yes | CC recipients |
+| `messages[].bcc` | string \\| null | yes | BCC recipients |
+| `messages[].snippet` | string | yes | Short plain-text preview of the email body (first ~255 chars) |
+| `messages[].conversationId` | string |  | Outlook conversation ID |
+| `messages[].receivedDateTime` | string |  | Received date-time in ISO format |
+| `messages[].hasAttachments` | boolean |  | Whether the email has attachments |
+| `messages[].importance` | string |  | Email importance level |
+| `messages[].isRead` | boolean |  | Whether the email has been read |
+| `messages[].isDraft` | boolean |  | Whether the email is a draft |
+| `messages[].flagStatus` | string |  | Flag status: notFlagged, complete, or flagged |
+| `messages[].classification` | string |  | Focused Inbox classification: focused or other |
+| `messages[].categories` | string[] |  | Color categories assigned to the email |
+
+### outlook_query_folders (workflow step)
+
+- List mail folders in an Outlook mailbox.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |
+| `parent_folder_id` | string |  | Parent folder ID to list child folders. Omit for top-level folders. |
+| `name` | string |  | Match folders by display name prefix. |
+| `include_hidden` | boolean |  | Include hidden system folders |
+| `max_result` | number |  | Maximum number of folders to return (1-100) |
+| `skip` | number |  | Number of results to skip for pagination |
+| `user_id` | string |  | The ID of the user whose mailbox to query. Defaults to the connected account owner. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `folders` | object[] | yes | List of mail folders |
+| `folders[].id` | string | yes | Folder ID |
+| `folders[].displayName` | string | yes | Folder display name |
+| `folders[].parentFolderId` | string |  | Parent folder ID |
+| `folders[].childFolderCount` | number | yes | Number of child folders |
+| `folders[].totalItemCount` | number | yes | Total number of items in the folder |
+| `folders[].unreadItemCount` | number | yes | Number of unread items |
+| `folders[].isHidden` | boolean | yes | Whether the folder is hidden |
+
+### outlook_read_email (workflow step)
+
+- Fetch an Outlook email's body and the list of its attachments.
+- Attachments are stored as workspace files — the result names each one's file_id; read one with view_files, attach one to a record with update_records. (workflow step, chat)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |
+| `message_id` | string | yes | The ID of the Outlook message to retrieve |
+| `user_id` | string |  | The ID of the user whose mailbox the email belongs to. If not provided, the connected account's user ID (me) will be used. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message` | object | yes | The full Outlook message |
+| `message.id` | string |  | Outlook message ID |
+| `message.date` | string | yes | Email date in the workspace timezone, with its offset |
+| `message.from` | string | yes | Sender email address |
+| `message.subject` | string | yes | Email subject |
+| `message.to` | string | yes | Recipient email address |
+| `message.cc` | string \\| null | yes | CC recipients |
+| `message.bcc` | string \\| null | yes | BCC recipients |
+| `message.inReplyTo` | string \\| null | yes | In-Reply-To header |
+| `message.replyTo` | string \\| null | yes | Reply-To header |
+| `message.references` | string[] \\| null | yes | References header |
+| `message.conversationId` | string |  | Outlook conversation ID |
+| `message.receivedDateTime` | string |  | Received date-time in ISO format |
+| `message.hasAttachments` | boolean |  | Whether the email has attachments |
+| `message.importance` | string |  | Email importance level |
+| `message.isRead` | boolean |  | Whether the email has been read |
+| `message.body` | object | yes | Email body |
+| `message.body.content` | string | yes | Body content |
+| `message.body.contentType` | "text" \\| "html" | yes | Body content type |
+| `message.attachments` | object[] |  | Email attachments |
+| `message.attachments[].id` | string | yes | Outlook attachment ID |
+| `message.attachments[].fileName` | string |  | Attachment filename as stored, which may differ from the sender's |
+| `message.attachments[].contentType` | string |  | MIME type as stored, recovered from the filename when Graph declared a generic one |
+| `message.attachments[].size` | number |  | Stored size in bytes |
+| `message.attachments[].file_id` | string |  | Stored file ID — pass to view_files to read it, or to update_records to attach it (workflow step, chat) |
+
+### outlook_reply_email (workflow step)
+
+- Draft or send a reply to an Outlook email.
+- Use reply_body (markdown) or template_id + template_data — not both.
+- Attach stored files by passing their file_ids.
+- Leaves an unsent draft unless draft is false.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |
+| `original_message_id` | string | yes |  |
+| `reply_body` | string |  | Reply body (markdown). Mutually exclusive with template_id. |
+| `template_id` | string |  |  |
+| `template_data` | object |  |  |
+| `cc` | string |  | CC recipients, comma-separated |
+| `bcc` | string |  | BCC recipients, comma-separated |
+| `draft` | boolean |  | Leave true to save an unsent draft the member reviews. Pass false only to deliver the message now — delivery is irreversible. |
+| `file_ids` | string[] | yes |  |
+| `user_id` | string |  | Mailbox user ID |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message_id` | string | yes | The ID of the sent message or saved draft |
+| `subject` | string | yes | The subject as sent |
+| `html` | string | yes | The body as sent, rendered to HTML |
+| `markdown` | string |  | The body as written in markdown; absent when a template rendered it |
+| `to` | string | yes | The original sender the reply went to |
+
+### outlook_send_email (workflow step)
+
+- Draft or send an Outlook email.
+- Use content (markdown) or template_id + template_data — not both.
+- Attach stored files by passing their file_ids.
+- Leaves an unsent draft unless draft is false, and while drafting 'to' may be omitted to leave the recipient line for the member to fill in.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | The Lotics connected account ID (cac_xxx), not the Microsoft user ID |
+| `to` | string |  | Recipient email(s), comma-separated. Required unless using a template. |
+| `subject` | string |  |  |
+| `cc` | string |  | CC recipients, comma-separated |
+| `bcc` | string |  | BCC recipients, comma-separated |
+| `content` | string |  | Email body (markdown). Mutually exclusive with template_id. |
+| `template_id` | string |  |  |
+| `template_data` | object |  |  |
+| `draft` | boolean |  | Leave true to save an unsent draft the member reviews. Pass false only to deliver the message now — delivery is irreversible. |
+| `file_ids` | string[] | yes |  |
+| `user_id` | string |  | Mailbox user ID |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message_id` | string | yes | The ID of the sent message or saved draft |
+| `subject` | string | yes | The subject as sent |
+| `html` | string | yes | The body as sent, rendered to HTML |
+| `markdown` | string |  | The body as written in markdown; absent when a template rendered it |
+| `to` | string \\| null | yes | The recipients as sent, comma-separated; null on a draft saved without recipients |
+
+## press
+
+### press_button (workflow step)
+
+- Run a button field's action against a record — equivalent to a user clicking the button in the UI.
+- Buttons are a legacy field type; the action must already be wired.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `table_id` | string | yes |  |
+| `record_id` | string | yes |  |
+| `field_key` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `execution_id` | string |  |  |
+| `status` | "success" \\| "error" |  |  |
+| `message` | string |  |  |
+
+## rename
+
+### rename_file (workflow step)
+
+- Get a file under another name: a new file over the same bytes.
+- Write its file_id into the files field in place of the old one; every other place holding the old file keeps its name.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `filename` | string | yes | The whole new name, keeping the file's extension exactly. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the generated file. |
+| `url` | string | yes | The download URL of the generated file. |
+| `filename` | string | yes | The filename of the generated file, including extension. |
+| `mime_type` | string | yes | The MIME type of the generated file. |
+
+## save
+
+### save_file (workflow step)
+
+- Save a file from a URL to the workspace.
+- Max 20MB.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `url` | string | yes | Public URL to download the file from (https:// or http://). |
+| `filename` | string |  | Filename with extension, e.g. 'report.pdf'. Derived from URL if omitted. |
+| `mime_type` | string |  | MIME type, e.g. 'application/pdf'. Derived from URL response if omitted. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `id` | string | yes | File ID. |
+| `filename` | string | yes |  |
+| `mime_type` | string | yes |  |
+| `url` | string | yes |  |
+
+## send
+
+### send_notification (workflow step)
+
+- Send a notification to workspace members. recipients is an array of principals: { type, id }.
+- All members: [{ type: "organization", id: "{{organization_id}}" }] Who triggered: [{ type: "member", id: "{{triggered_by_member_id}}" }] A group: [{ type: "member_group", id: "<group_id>" }]
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `recipients` | any[] | yes | List of recipients. Each entry is a principal: { type: 'member', id } \| { type: 'member_group', id } \| { type: 'organization', id } |
+| `title` | string | yes |  |
+| `body` | string | yes |  |
+| `level` | "urgent" \\| "warning" \\| "info" \\| "success" |  | Notification level: urgent, warning, info, success |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message` | string | yes |  |
+| `recipients_count` | number | yes |  |
+
+## telegram
+
+### telegram_list_chats (workflow step)
+
+- List the chats that messaged a Telegram bot, or added it, in the last 24 hours — where a chat id comes from.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Telegram connected account |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `chats` | object[] | yes |  |
+| `chats[].chat_id` | string | yes |  |
+| `chats[].type` | string | yes | private, group, supergroup or channel |
+| `chats[].name` | string | yes |  |
+| `chats[].username` | string |  |  |
+| `chats[].last_seen_at` | string | yes | ISO timestamp of the chat's latest update |
+
+### telegram_send_document (workflow step)
+
+- Send a stored file from a Telegram bot to a chat, as a document with an optional caption.
+- The chat must have messaged the bot first.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Telegram connected account |
+| `chat_id` | string | yes | Numeric chat id, or the @username of a public channel or group |
+| `file_id` | string | yes |  |
+| `caption` | string |  |  |
+| `parse_mode` | "HTML" \\| "MarkdownV2" |  | How the text is formatted: Telegram's HTML tags or its MarkdownV2 syntax |
+| `disable_notification` | boolean |  | Deliver without a notification sound |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message_id` | number | yes |  |
+| `chat_id` | string | yes |  |
+| `sent_at` | string | yes | ISO timestamp |
+
+### telegram_send_message (workflow step)
+
+- Send a text message from a Telegram bot to a chat.
+- The chat must have messaged the bot first.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes | Telegram connected account |
+| `chat_id` | string | yes | Numeric chat id, or the @username of a public channel or group |
+| `text` | string | yes |  |
+| `parse_mode` | "HTML" \\| "MarkdownV2" |  | How the text is formatted: Telegram's HTML tags or its MarkdownV2 syntax |
+| `disable_notification` | boolean |  | Deliver without a notification sound |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `message_id` | number | yes |  |
+| `chat_id` | string | yes |  |
+| `sent_at` | string | yes | ISO timestamp |
+
+## threads
+
+### threads_create_post (workflow step)
+
+- Publish a post to the connected Threads account.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `text` | string | yes |  |
+| `link` | string |  | Shown as a link card. A post carries either a link or media. |
+| `media_file_ids` | string[] |  | One image or video, or 2–20 images and videos as a carousel. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `post_id` | string | yes |  |
+| `url` | string | yes |  |
+
+## vietcombank
+
+### vietcombank_convert_currency (workflow step)
+
+- Convert between currencies using live Vietcombank exchange rates.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `from_currency` | string | yes | Source currency code (e.g., 'USD', 'EUR', 'JPY') |
+| `to_currency` | string | yes | Target currency code (e.g., 'USD', 'EUR', 'JPY') |
+| `amount` | number | yes | The amount to convert (must be positive) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `converted_amount` | number | yes | The converted amount |
+| `exchange_rate` | number | yes | The exchange rate |
+
+## view
+
+### view_files (workflow step)
+
+- View one or more files in a single call.
+- Two modes: - file_ids: explicit list of file IDs (use for cherry-picked files). - source: every file attached to a record's file field (use when you want all photos/attachments on a record).
+- Provide exactly one.
+- Reads EVERY readable format: images, PDFs, Word (.docx and legacy .doc), Excel (.xlsx and legacy .xls), CSV, and text formats (.txt, .md, .json, .xml, .yaml, .html).
+- Batch limit: 100 files.
+- Use this whenever you are handed a file_id you cannot already see — images and PDFs arrive in your context natively, but every other format is a reference you must open with this tool.
+- Files already in your context — those the user attached to the current message, and those an earlier view_files call returned this conversation — return a text-only "already in context" reference instead of re-emitting bytes. (workflow step, chat)
+- You do not need to re-call view_files to look at the same image again; scroll back to the original tool_result. (workflow step, chat)
+- Calling with already-seen file_ids is safe but wasteful.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_ids` | string[] |  |  |
+| `source` | object |  |  |
+| `source.record_id` | string | yes |  |
+| `source.field_key` | string | yes |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `files` | object[] | yes |  |
+| `files[].file_id` | string | yes |  |
+| `files[].filename` | string | yes |  |
+| `files[].mime_type` | string | yes |  |
+| `files[].content` | object |  |  |
+| `files[].already_in_context` | boolean |  |  |
+| `files[].error` | string |  |  |
+
+## wininvoice
+
+### wininvoice_create_or_update_invoice (workflow step)
+
+- Create or update a Vietnamese e-invoice in WinInvoice. invRef identifies the invoice: a value that already has one resolves to that invoice rather than issuing a new one, and isExisting: 1 means it came back unchanged with nothing issued.
+- Derive invRef from what is being billed rather than from a record that may later describe something else.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `invName` | string | yes | Invoice sample name, ex: 1,2,6 |
+| `invSerial` | string | yes | Invoice sign, ex: C24TAA, K24TXX |
+| `invNumber` | string | yes | Invoice number |
+| `invDate` | string | yes | Invoice date (format: yyyy/mm/dd) |
+| `invCustomer` | 0 \\| 1 |  | Customer is not company? Value 1\|0 |
+| `invRef` | string | yes | 3rd party Bill-ID. Identifies the invoice: a value that already has an invoice resolves to that invoice instead of issuing a new one |
+| `invRefDate` | string |  | Bill date (format: yyyy/mm/dd) |
+| `billNumber` | string |  | Bill number - extend |
+| `buyerTax` | string |  | Buyer tax-number |
+| `buyerCode` | string |  | Buyer-id |
+| `buyerName` | string | yes | Buyer full name |
+| `buyerCompany` | string |  | Buyer company/ organization name |
+| `buyerAddress` | string |  | Buyer full address |
+| `buyerAcc` | string |  | Buyer bank account number |
+| `buyerBank` | string |  | Buyer bank name |
+| `buyerEmail` | string |  | Buyer email |
+| `buyerPhone` | string |  | Buyer phone number |
+| `buyerFax` | string |  | Buyer fax number |
+| `buyerCitizenIDNumber` | string |  | Citizen Identification Number |
+| `buyerPassportNumber` | string |  | Passport Number |
+| `govUnitCode` | string |  | Budget-related Unit Code |
+| `invSubTotal` | number | yes | Invoice Subtotal (not include VAT, not include discount) |
+| `invVatRate` | number | yes | VAT Rate: 0,5,8,10 (0%,5%,8%,10%), -1 (Not taxable), -2 (Not declare and pay taxes) |
+| `invVatAmount` | number | yes | VAT Amount |
+| `invTotalAmount` | number | yes | Invoice Total |
+| `invPayment` | string |  | Payment method |
+| `invExchangeRate` | number |  | Exchange rate (to VietNam đồng) |
+| `invCurrency` | string |  | Payment currency |
+| `note` | string |  | Note for discount |
+| `invAutoSign` | 0 \\| 1 |  | Request sign invoice immediately after create successful? Value 1\|0 |
+| `privateCode` | string |  | The UID string (10-12 chars), the buyer will use this code to lookup invoice (after invoice signed). If blank, WinInvoice will generate automatically |
+| `option` | 0 \\| 1 \\| 2 \\| 3 \\| 4 |  | Invoice type: 0 (Normal invoice), 1 (Information-adjustment invoice), 2 (Increases-adjustment invoice), 3 (Decreases-adjustment invoice), 4 (Replacement invoice - original will be marked as deleted when signed) |
+| `invCodeOld` | string |  | Original invoice number (required for adjustment/replacement invoices) |
+| `invNameOld` | string |  | Original invoice sample name (required for adjustment/replacement invoices) |
+| `invSignOld` | string |  | Original invoice sign (required for adjustment/replacement invoices) |
+| `create04SSHDDT` | 0 \\| 1 |  | Auto create 04/SS-HĐĐT? Value 1\|0 (default 1) |
+| `reason04SSHDDT` | string |  | 04/SS-HĐĐT Reason |
+| `isDscnForSaleInv` | 0 \\| 1 |  | Apply an 8% tax reduction to the sales invoice? Value 1\|0 (default 0) |
+| `saleInvVATRate` | number |  | Tax rate based on revenue (Only applicable when isDscnForSaleInv = 1) |
+| `saleInvDscnAmnt` | number |  | The reduction amount determined based on revenue and corresponding tax rate (Only applicable when isDscnForSaleInv = 1) |
+| `privateNote` | string |  | Used for internal notes |
+| `items` | object[] | yes | Array of item/product in this bill |
+| `items[].itemNo` | string |  | Item number |
+| `items[].itemCode` | string |  | Product/Item code |
+| `items[].itemName` | string | yes | Name of product |
+| `items[].itemPromo` | 0 \\| 1 |  | Is promotional product (gift)? Value 1\|0 (default 0) |
+| `items[].isDscnItem` | 0 \\| 1 |  | Is the discount line? Value 1\|0 (default 0) |
+| `items[].itemUnit` | string |  | Product Unit |
+| `items[].itemQuantity` | number | yes | Product quantity |
+| `items[].itemPrice` | number | yes | Product unit price (not include VAT) |
+| `items[].itemVatRate` | number |  | Product VAT rate |
+| `items[].itemVatAmnt` | number |  | Product VAT Amount |
+| `items[].itemDscnAmnt` | number |  | Product Discount Amount |
+| `items[].itemAmountNoVat` | number |  | Product Amount (not include VAT)(not include item discount) |
+| `items[].adjustType` | "PRICE" \\| "QTTY" |  | Type of adjustment: PRICE (Adjust unit price of item in original invoice), QTTY (Adjust quantity of item in original invoice). This field has effect when value of option field is 2 or 3 |
+| `items[].itemPack` | string |  | Product Lot |
+| `items[].itemDate` | string |  | Product expiration date |
+| `items[].itemNote` | string |  | Product note |
+| `items[].specialGoodsType` | 0 \\| 1 \\| 2 \\| 3 |  | Special category of goods: 0 (Normal item/good), 1 (Cars or motorcycles), 2 (Transportation service), 3 (Transportation services on digital and e-commerce platforms) |
+| `items[].specialGoodsInfo` | object |  | Data requirements for specialized goods based on specialGoodsType |
+| `items[].specialGoodsInfo.chassisNumb` | string |  | Chassis Number (for cars/motorcycles - specialGoodsType = 1) |
+| `items[].specialGoodsInfo.engineNumb` | string |  | Engine Number (for cars/motorcycles - specialGoodsType = 1) |
+| `items[].specialGoodsInfo.licensePlate` | string |  | License plate of the transport vehicle (for transportation service - specialGoodsType = 2) |
+| `items[].specialGoodsInfo.senderName` | string |  | Sender's Name (for shipping service - specialGoodsType = 3) |
+| `items[].specialGoodsInfo.senderAddress` | string |  | Sender's Address (for shipping service - specialGoodsType = 3) |
+| `items[].specialGoodsInfo.senderTaxCode` | string |  | Sender's Tax Code (for shipping service - specialGoodsType = 3) |
+| `items[].specialGoodsInfo.senderCitizenIDNumber` | string |  | Sender's Citizen Identification Number (for shipping service - specialGoodsType = 3) |
+| `items[].isNoteItem` | 0 \\| 1 |  | Is the note line? Value 1\|0 (default 0) |
+| `connected_account_id` | string | yes | The ID of the connected account |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `oid` | string | yes | WinInvoice's UID |
+| `invCode` | string | yes | Invoice number (is '0000000' if has not signed) |
+| `invRef` | string | yes | 3rd party Bill-ID |
+| `invSign` | string | yes | Invoice sign, (as invSerial) |
+| `invDate` | string | yes | Invoice date, format yyyy-mm-dd |
+| `invName` | string | yes | Full invoice sample (invName + invSign) |
+| `privateCode` | string | yes | Private lookup code for buyer |
+| `itemTotal` | number |  | Count of products in invoice |
+| `itemError` | number |  | Count of error-products in invoice |
+| `govTranfer` | number | yes | Invoice has transferred to GOV? 1\|0 |
+| `govTranID` | string | yes | Transaction ID used to transfer invoice to GOV |
+| `govTranferErr` | number | yes | ansferred to GOV has FAIL? 1\|0 |
+| `govTranText` | string | yes | Error message if transfer to GOV has FAIL |
+| `govCode` | string | yes | The UID string issue by GOV for this invoice |
+| `autoSign` | number |  | Has request sign immediately ? 1\|0 |
+| `isExisting` | 0 \\| 1 |  | 1 when invRef already had an invoice and this call returned it unchanged — no invoice was issued |
+| `link` | string | yes | Link to view the invoice |
+
+## word
+
+### word_create_document (workflow step)
+
+- Create a new Word document (.docx), optionally with initial paragraphs and headings.
+- Use {{variable_name}} syntax in text to create template placeholders for data injection via create_word_template. (workflow step, chat, MCP, CLI)
+- Input: { filename, content?: [{ type: "paragraph"\|"heading", text, level?: 1-6 }] } filename is without the .docx extension (added automatically).
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `filename` | string | yes | Name of the file (without .docx extension) |
+| `content` | object[] |  |  |
+| `content[].type` | "paragraph" \\| "heading" | yes |  |
+| `content[].text` | string | yes |  |
+| `content[].level` | number |  | Heading level (1-6), required when type is heading |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the generated file. |
+| `url` | string | yes | The download URL of the generated file. |
+| `filename` | string | yes | The filename of the generated file, including extension. |
+| `mime_type` | string | yes | The MIME type of the generated file. |
+
+### word_find_text (workflow step)
+
+- Search for text across all paragraphs and table cells in a Word document.
+- Input: { file_id, query: "search text", match_type?: "contains"\|"exact"\|"regex", max_results?: number } Default match_type is "contains".
+- Returns matching element indices, types, and text content.
+- Read-only — does not modify the file.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the Word (.docx) file |
+| `query` | string | yes |  |
+| `match_type` | "contains" \\| "exact" \\| "regex" |  |  |
+| `max_results` | number |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `matches` | object[] | yes |  |
+| `matches[].index` | number | yes |  |
+| `matches[].type` | "paragraph" \\| "table" \\| "other" | yes |  |
+| `matches[].text` | string | yes |  |
+| `total` | number | yes |  |
+
+### word_get_content (workflow step)
+
+- Read a Word document's full native content, paginated.
+- Every element returned is COMPLETE — full paragraph text and full table cells — unlike view_files, whose quick-look preview truncates long paragraphs and tables. (workflow step, chat)
+- Input: { file_id, offset?, limit? }.
+- Returns elements with their 0-based indices plus next_offset when more remains; call again with offset=next_offset to continue.
+- A page may end before `limit` to keep elements whole — follow next_offset, don't infer completion from the count.
+- A selection mark — a highlighted, shaded or coloured run, or a shaded table cell — surfaces in `marked_text` (the paragraph with each mark shown where it falls, which is what tells you WHICH of two identical `□` was picked), `highlighted_spans` (the marked text alone) and `marked_cells` (per table), so a form's chosen option reads correctly even when it is marked by colour rather than a tick.
+- Bold is OFF by default and reported only with `include_bold`, as a FACT rather than a selection: nearly every heading and label is bold, so on most documents it is noise.
+- Reach for it when a form's chosen option carries no glyph and no colour — some forms record the choice by bolding the chosen option's label, and then bold is the tick's only trace.
+- On a PARAGRAPH, `formatting_hint` already says the line contains bold (it cannot say which run — that is what `bold_spans` adds).
+- A TABLE carries no such hint, so on a criteria or option table pass `include_bold` rather than waiting for a signal.
+- Read the result against its siblings: a wholly bold heading or header row is structure, one bold label among plain ones is the choice.
+- Footnotes surface in `footnote_refs` (per paragraph) and `footnote_cells` (per table) with the note's own text, since a clause often carries its rule in the footnote rather than the sentence.
+- `orphaned_footnotes` lists notes the file carries with no anchor left in the body — those render nowhere.
+- Pictures surface in `images` on the element holding them, so a paragraph carrying only a picture is not mistaken for an empty one.
+- `headers_footers` carries header and footer text, which sits outside the body and so has no element index — a form often states which form it is there rather than in its text.
+- Read-only — does not modify the file.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the Word (.docx) file |
+| `offset` | integer |  | Element index to start from (pass the prior call's next_offset) |
+| `limit` | integer |  | Max elements to return |
+| `include_bold` | boolean |  | Also report WHERE the bold runs are (bold_spans / bold_cells). Off unless asked for — nearly every heading and label is bold, so it is noise on most documents and the answer on a form that ticks by bolding. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `elements` | object[] | yes |  |
+| `elements[].index` | number | yes |  |
+| `elements[].type` | "paragraph" \\| "table" \\| "other" | yes |  |
+| `elements[].text` | string |  |  |
+| `elements[].rows` | number |  |  |
+| `elements[].cols` | number |  |  |
+| `elements[].cells` | string[][] |  |  |
+| `elements[].heading_level` | number |  |  |
+| `elements[].list_type` | "bullet" \\| "numbered" |  |  |
+| `elements[].list_level` | number |  |  |
+| `elements[].formatting_hint` | string |  |  |
+| `elements[].highlighted_spans` | string[] |  |  |
+| `elements[].bold_spans` | string[] |  |  |
+| `elements[].marked_text` | string |  |  |
+| `elements[].images` | object[] |  |  |
+| `elements[].images[].name` | string |  |  |
+| `elements[].images[].width_cm` | number |  |  |
+| `elements[].images[].height_cm` | number |  |  |
+| `elements[].marked_cells` | object[] |  |  |
+| `elements[].marked_cells[].row` | number | yes |  |
+| `elements[].marked_cells[].col` | number | yes |  |
+| `elements[].marked_cells[].spans` | string[] | yes |  |
+| `elements[].bold_cells` | object[] |  |  |
+| `elements[].bold_cells[].row` | number | yes |  |
+| `elements[].bold_cells[].col` | number | yes |  |
+| `elements[].bold_cells[].spans` | string[] | yes |  |
+| `elements[].footnote_refs` | object[] |  |  |
+| `elements[].footnote_refs[].mark` | number | yes | The superscript number the reader sees |
+| `elements[].footnote_refs[].id` | string | yes |  |
+| `elements[].footnote_refs[].offset` | number | yes | Character offset into this element's text where the mark sits |
+| `elements[].footnote_refs[].text` | string |  |  |
+| `elements[].footnote_cells` | object[] |  |  |
+| `elements[].footnote_cells[].row` | number | yes |  |
+| `elements[].footnote_cells[].col` | number | yes |  |
+| `elements[].footnote_cells[].refs` | object[] | yes |  |
+| `elements[].footnote_cells[].refs[].mark` | number | yes | The superscript number the reader sees |
+| `elements[].footnote_cells[].refs[].id` | string | yes |  |
+| `elements[].footnote_cells[].refs[].offset` | number | yes | Character offset into this element's text where the mark sits |
+| `elements[].footnote_cells[].refs[].text` | string |  |  |
+| `total` | number | yes |  |
+| `next_offset` | number \\| null | yes |  |
+| `orphaned_footnotes` | object[] |  | Notes the file still carries with no anchor left in the body — they render nowhere |
+| `orphaned_footnotes[].id` | string | yes |  |
+| `orphaned_footnotes[].text` | string | yes |  |
+| `headers_footers` | object[] |  | Header and footer text — outside the body, so it carries no element index |
+| `headers_footers[].kind` | "header" \\| "footer" | yes |  |
+| `headers_footers[].text` | string | yes |  |
+
+### word_get_table_data (workflow step)
+
+- Read the full contents of a table in a Word document as a 2D string array.
+- Input: { file_id, table_index: number, max_rows? } table_index is the 0-based element index from view_files (must point to a table element). (workflow step, chat)
+- Returns data[][] with row_count and col_count.
+- A cell carrying a selection mark — a highlighted or shaded run, or a shaded cell — is listed in `marked_cells` ({row, col} aligned with data, spans = the marked text; empty spans = a shaded blank), so a criteria row's chosen option reads correctly even when it is marked by colour rather than a tick.
+- `bold_cells` lists the bold cells the same way, but ONLY with `include_bold` — header rows and label columns are bold, so it is noise on most tables.
+- Nothing in the default output hints that a table contains bold, so pass it whenever a criteria or option table shows no glyph and no colour: some forms record the choice by bolding that row's label and it is the tick's only trace.
+- It is a fact, never a selection — a whole bold header row is structure, one bold label among plain siblings is the choice.
+- Read-only — does not modify the file.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the Word (.docx) file |
+| `table_index` | number | yes | 0-based element index of the table |
+| `max_rows` | number |  | Max rows to return; all rows when omitted |
+| `include_bold` | boolean |  | Also report which cells are bold (bold_cells). Off unless asked for — header rows and label columns are bold, so it is noise on most tables and the answer on one that ticks by bolding. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `data` | string[][] | yes |  |
+| `row_count` | number | yes |  |
+| `col_count` | number | yes |  |
+| `marked_cells` | object[] |  |  |
+| `marked_cells[].row` | number | yes |  |
+| `marked_cells[].col` | number | yes |  |
+| `marked_cells[].spans` | string[] | yes |  |
+| `bold_cells` | object[] |  |  |
+| `bold_cells[].row` | number | yes |  |
+| `bold_cells[].col` | number | yes |  |
+| `bold_cells[].spans` | string[] | yes |  |
+
+### word_insert_conditional (workflow step)
+
+- Insert {{IF variable_name}}...{{END-IF variable_name}} command rows or paragraphs into a Word document to define a conditional section.
+- For table_rows: wraps the specified row range with command rows.
+- Requires table_index, start_row, end_row.
+- For paragraphs: wraps the specified element range with command paragraphs.
+- Requires start_index, end_index.
+- Use view_files to find element indices first. (workflow step, chat)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `variable_name` | string | yes | Boolean variable name |
+| `region_type` | "table_rows" \\| "paragraphs" | yes |  |
+| `table_index` | integer |  | Index of the table element (required for table_rows) |
+| `start_row` | integer |  | First row to wrap (required for table_rows) |
+| `end_row` | integer |  | Last row to wrap, inclusive (required for table_rows) |
+| `start_index` | integer |  | First element index to wrap (required for paragraphs) |
+| `end_index` | integer |  | Last element index to wrap, inclusive (required for paragraphs) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+
+### word_insert_loop (workflow step)
+
+- Insert {{FOR loop_var IN variable_name}}...{{END-FOR loop_var}} command rows or paragraphs into a Word document to define a repeating section.
+- Inside the loop, reference each item's fields with a $ prefix: {{$loop_var.field}} (or {{$loop_var}} for a scalar item, {{$idx}} for the 0-based index).
+- Without the $ prefix, generation fails.
+- For table_rows: wraps the specified row range with command rows.
+- Requires table_index, start_row, end_row.
+- For paragraphs: wraps the specified element range with command paragraphs.
+- Requires start_index, end_index.
+- Use view_files to find element indices first. (workflow step, chat)
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `variable_name` | string | yes | Array variable name |
+| `loop_variable` | string | yes | Iterator name used inside the loop, e.g. item |
+| `region_type` | "table_rows" \\| "paragraphs" | yes |  |
+| `table_index` | integer |  | Index of the table element (required for table_rows) |
+| `start_row` | integer |  | First row to wrap (required for table_rows) |
+| `end_row` | integer |  | Last row to wrap, inclusive (required for table_rows) |
+| `start_index` | integer |  | First element index to wrap (required for paragraphs) |
+| `end_index` | integer |  | Last element index to wrap, inclusive (required for paragraphs) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+
+### word_replace_text (workflow step)
+
+- Find and replace text across all paragraphs and table cells in a Word document.
+- Replaces all occurrences unless max_replacements is set.
+- A match spanning several runs collapses them into the first run's formatting, so tick a checkbox by matching the box character on its own — ☐ (U+2610) becomes ☒ (U+2612), keeping the font that draws both.
+- Matching the phrase around the box drags it into the body font; replacing it with a letter leaves a bare letter beside the boxes still showing ☐.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the Word (.docx) file |
+| `find` | string | yes |  |
+| `replace` | string | yes |  |
+| `match_type` | "contains" \\| "exact" \\| "regex" |  | `exact` matches a whole paragraph. None of the three is case-sensitive. |
+| `max_replacements` | number |  | Max number of replacements (default: unlimited) |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes |  |
+| `replacements_made` | number | yes |  |
+
+## x
+
+### x_create_post (workflow step)
+
+- Publish a post to the connected X account.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `connected_account_id` | string | yes |  |
+| `text` | string | yes |  |
+| `media_file_ids` | string[] |  | Up to 4 images, or one GIF, or one video. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `post_id` | string | yes |  |
+| `url` | string | yes |  |
+
+## zip
+
+### zip_files (workflow step)
+
+- Bundle multiple files into a zip archive.
+- Max 100 files.
+- An item in file_ids is a file id — or `{ id, name }` to name that entry in the archive: a file name, never a path, carrying the stored extension.
+- A bare id keeps the stored filename.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_ids` | string \\| object[] | yes |  |
+| `filename` | string |  | Name for the zip file, without the .zip extension. |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `file_id` | string | yes | The ID of the generated file. |
+| `url` | string | yes | The download URL of the generated file. |
+| `filename` | string | yes | The filename of the generated file, including extension. |
+| `mime_type` | string | yes | The MIME type of the generated file. |