csf_tz.custom_api Function Documentation
This document provides categorized documentation for all functions defined in custom_api.py, including their name, description, parameters, and example usage.
1. QR Code Utilities
generate_qrcode(qrcode_data)
Description: Generates a base64-encoded PNG QR code image from the provided string data.
Parameters:
qrcode_data(str): The data to encode into a QR code.
Example:
qr_image = generate_qrcode("https://example.com")
2. Error Logging and Debugging
app_error_log(title, error)
Description: Logs the most recent traceback to Frappe error logs.
Parameters:
title(str): Title for the error log.error(str): Description or message of the error.
Example:
app_error_log("Database Error", "Unable to connect")
print_out(message, alert=False, add_traceback=False, to_error_log=False)
Description: Prints and optionally logs or alerts a message, with support for tracebacks.
Parameters:
message: The message to output.alert(bool): Show message as alert.add_traceback(bool): Include traceback in log.to_error_log(bool): Log to Frappe error log.
Example:
print_out("Processing complete", alert=True)
3. Currency and Exchange Rate Handling
getInvoiceExchangeRate(date, currency)
Description: Retrieves the exchange rate between the specified currency and the default company currency for a given date.
Parameters:
date(str): The date in string format.currency(str): The foreign currency code.
Example:
rate = getInvoiceExchangeRate("2024-12-31", "KES")
getInvoice(currency, name)
Description: Fetches Sales and Purchase Invoices requiring revaluation based on exchange rate differences.
Parameters:
currency(str): The currency to revaluate.name(str): Document name of the revaluation parent.
Example:
invoices = getInvoice("USD", "REVAL-0003")
addChildItem(name, inv_no, invoice_type, invoice_exchange_rate, invoice_currency, invoice_amount, current_exchange, idx)
Description: Inserts a child entry to document gain/loss resulting from exchange rate differences.
Parameters:
name(str): Parent document name.inv_no(str): Invoice number.invoice_type(str): Type of invoice (Sales or Purchase).invoice_exchange_rate(float): Original exchange rate.invoice_currency(str): Invoice currency.invoice_amount(float): Invoice total amount.current_exchange(float): Current exchange rate.idx(int): Row index.
Example:
addChildItem("REVAL-0003", "PINV-0012", "Purchase Invoice", 1.18, "USD", 500, 1.10, 2)
4. Stock and Inventory
get_stock_ledger_entries(item_code)
Description: Retrieves the latest stock ledger entries for a given item code.
Parameters:
item_code(str): Item code to check.
Example:
entries = get_stock_ledger_entries("ITEM-001")
get_version()
Description: Detects the current ERPNext version based on the app branch name.
Parameters:
None
Example:
version = get_version()
get_app_branch(app)
Description: Returns the current Git branch name for a given app.
Parameters:
app(str): The application folder name (e.g., "erpnext").
Example:
branch = get_app_branch("erpnext")
get_item_info(item_code)
Description: Returns batch-wise item quantities and expiry statuses for a given item.
Parameters:
item_code(str): Item code to fetch info for.
Example:
info = get_item_info("ITEM-123")
5. Pricing and Sales History
get_item_prices(item_code, currency, customer=None, company=None)
Description: Fetches historical prices for a given item from sales invoices.
Parameters:
item_code(str): Item code.currency(str): Currency code.customer(str, optional): Customer name.company(str, optional): Company name.
Example:
prices = get_item_prices("ITEM-001", "USD", customer="Customer A", company="MyCo")
get_item_prices_custom(filters=None, start=0, limit=20)
Description: Fetches item prices with filter options and pagination.
Parameters:
filters(dict|str): JSON or dict of filters.start(int): Pagination start.limit(int): Pagination limit.
Example:
prices = get_item_prices_custom({"item_code": "ITEM-001", "customer": "Cust A"})
6. Repacking Operations
get_repack_template(template_name, qty)
Description: Fetches item and component rows from a repack template, scaled by a given quantity.
Parameters:
template_name(str): Name of the Repack Template.qty(int): Desired output quantity.
Example:
rows = get_repack_template("REPACK-001", 5)
7. Delivery Note Automation
create_delivery_note(doc=None, method=None, doc_name=None)
Description: Automatically creates a delivery note from a sales invoice if conditions are met.
Parameters:
doc: Sales Invoice document (optional).method: Hook method triggering this (optional).doc_name: Sales Invoice name (optional).
Example:
create_delivery_note(doc_name="SINV-001")
check_item_is_maintain(item_name)
Description: Checks if the item is a stock item.
Parameters:
item_name(str): Item code.
Example:
check_item_is_maintain("ITEM-001")
make_delivery_note(source_name, target_doc=None, set_warehouse=None)
Description: Maps a Sales Invoice to a Delivery Note with necessary transformations.
Parameters:
source_name(str): Name of the Sales Invoice.target_doc: Optional target document to populate.set_warehouse(str): Warehouse to set.
Example:
dn = make_delivery_note("SINV-001")
...
8. Indirect Expense Management
create_indirect_expense_item(doc, method=None)
Description: Automatically creates or updates an "Indirect Expenses" item linked to an account.
Parameters:
doc: The Account document.method: Triggering method (optional).
Example:
create_indirect_expense_item(account_doc)
check_expenses_in_parent_accounts(account_name)
Description: Checks if the specified account or its parents fall under 'Indirect Expenses'.
Parameters:
account_name(str): Name of the account to check.
Example:
is_indirect = check_expenses_in_parent_accounts("Expense Account")
add_indirect_expense_item(account_name)
Description: Wrapper to call create_indirect_expense_item() using account name.
Parameters:
account_name(str): Name of the Account.
Example:
add_indirect_expense_item("Expense Account")
9. Document Relationship Handling
get_linked_docs_info(doctype, docname)
Description: Retrieves metadata for documents linked to a given document.
Parameters:
doctype(str): The base document type.docname(str): Name of the document.
Example:
links = get_linked_docs_info("Sales Invoice", "SINV-0001")
cancle_linked_docs(doc_list)
Description: Recursively cancels linked documents.
Parameters:
doc_list(list): List of linked document metadata.
Example:
cancle_linked_docs(linked_docs)
delete_linked_docs(doc_list)
Description: Recursively deletes linked documents and cancels them if needed.
Parameters:
doc_list(list): List of linked document metadata.
Example:
delete_linked_docs(linked_docs)
cancel_doc(doctype, docname)
Description: Cancels a document if it’s submitted.
Parameters:
doctype(str): Doctype to cancel.docname(str): Document name.
Example:
cancel_doc("Stock Entry", "STE-001")
delete_doc(doctype, docname)
Description: Deletes a document, canceling it first if submitted.
Parameters:
doctype(str): Doctype.docname(str): Document name.
Example:
delete_doc("Stock Entry", "STE-001")
10. Material Requests and Stock Reconciliation
get_pending_material_request()
Description: Returns a list of pending Material Requests.
Parameters: None
Example:
pending_requests = get_pending_material_request()
make_stock_reconciliation(items, company)
Description: Creates a draft Stock Reconciliation document using provided items.
Parameters:
items(list): List of item dicts with reconciliation data.company(str): Company name.
Example:
make_stock_reconciliation(item_list, "My Company")
make_stock_reconciliation_for_all_pending_material_request(*args)
Description: Creates stock reconciliations for all pending material requests.
Parameters:
*args: Optional arguments (not used in logic).
Example:
make_stock_reconciliation_for_all_pending_material_request()
11. Validation and Stock Checks
validate_item_remaining_qty(item_code, company, warehouse=None, stock_qty=None, so_detail=None)
Description: Validates if there's enough stock for an item before allowing transaction.
Parameters:
item_code(str): Item code.company(str): Company name.warehouse(str): Warehouse name (optional).stock_qty(float): Quantity being validated.so_detail(str): Sales Order detail reference (optional).
Example:
validate_item_remaining_qty("ITEM-001", "Company A", "Main Warehouse", 10)
validate_items_remaining_qty(doc, method)
Description: Loops through a document’s items and validates stock quantity.
Parameters:
doc: Document with items (e.g. Sales Order).method: Hook method name.
Example:
validate_items_remaining_qty(sales_order_doc, "validate")
12. Delivery Note Status Updates
check_validate_delivery_note(doc=None, method=None, doc_name=None)
Description: Updates delivery status fields in Sales Invoice based on actual deliveries.
Parameters:
doc: Sales Invoice document (optional).method: Triggering method (optional).doc_name: Sales Invoice name (optional).
Example:
check_validate_delivery_note(doc_name="SINV-0005")
check_submit_delivery_note(doc, method)
Description: Updates delivery status upon submission of Delivery Note.
Parameters:
doc: Delivery Note document.method: Triggering method.
Example:
check_submit_delivery_note(delivery_note_doc, "on_submit")
check_cancel_delivery_note(doc, method)
Description: Updates delivery status on cancellation of Delivery Note.
Parameters:
doc: Delivery Note document.method: Triggering method.
Example:
check_cancel_delivery_note(delivery_note_doc, "on_cancel")
update_delivery_on_sales_invoice(doc, method)
Description: Updates delivery status on Sales Invoice after a linked Delivery Note is submitted.
Parameters:
doc: Delivery Note document.method: Hook method.
Example:
update_delivery_on_sales_invoice(delivery_note_doc, "on_submit")
get_delivery_note_item_count(item_row_name, sales_invoice)
Description: Returns quantity delivered for a specific item in a Sales Invoice.
Parameters:
item_row_name(str): Row name in Sales Invoice.sales_invoice(str): Sales Invoice name.
Example:
qty = get_delivery_note_item_count("SINV-ITEM-0001", "SINV-0001")
13. Pending Sales Invoice Handling
get_pending_sales_invoice(*args)
Description: Returns a list of pending sales invoices based on filters like customer, warehouse, and posting date.
Parameters:
*args: A list of six elements including filters, pagination info, etc.
Example:
pending_invoices = get_pending_sales_invoice("", "", 0, 10, {"customer": "Cust1"})
get_list_pending_sales_invoice(invoice_name=None, warehouse=None)
Description: Returns pending invoices optionally filtered by invoice name or warehouse.
Parameters:
invoice_name(str, optional): Sales Invoice name.warehouse(str, optional): Warehouse name.
Example:
pending_list = get_list_pending_sales_invoice("SINV-0001")
create_delivery_note_for_all_pending_sales_invoice(doc=None, method=None)
Description: Automatically creates delivery notes for all pending invoices per company settings.
Parameters:
doc: Not used.method: Not used.
Example:
create_delivery_note_for_all_pending_sales_invoice()
14. Item Quantity Calculations
get_pending_si_delivery_item_count(item_code, company, warehouse)
Description: Returns the pending quantity to deliver for Sales Invoices not linked to Sales Orders.
Parameters:
item_code(str): Item code.company(str): Company name.warehouse(str): Warehouse name.
Example:
qty = get_pending_si_delivery_item_count("ITEM-001", "Company A", "WH-001")
get_pending_delivery_item_count(item_code, company, warehouse)
Description: Returns the pending quantity to deliver for items in open Sales Orders.
Parameters:
item_code(str): Item code.company(str): Company name.warehouse(str): Warehouse name.
Example:
qty = get_pending_delivery_item_count("ITEM-001", "Company A", "WH-001")
get_item_balance(item_code, company, warehouse=None)
Description: Returns the available balance quantity for an item, considering child warehouses.
Parameters:
item_code(str): Item code.company(str): Company name.warehouse(str, optional): Warehouse name.
Example:
balance = get_item_balance("ITEM-001", "Company A")
15. Withholding Tax Journal Entries
make_withholding_tax_gl_entries_for_purchase(doc, method)
Description: Creates GL entries for purchase withholding tax, and optionally submits the journal entry.
Parameters:
doc: Purchase Invoice document.method: Calling method or "From Front End" string.
Example:
make_withholding_tax_gl_entries_for_purchase(pinv_doc, "on_submit")
make_withholding_tax_gl_entries_for_sales(doc, method)
Description: Creates GL entries for sales withholding tax, and optionally submits the journal entry.
Parameters:
doc: Sales Invoice document.method: Calling method or "From Front End" string.
Example:
make_withholding_tax_gl_entries_for_sales(sinv_doc, "on_submit")
16. Student Enrollment Tools
enroll_all_students(self)
Description: Enqueues or immediately enrolls students from Program Enrollment Tool.
Parameters:
self: JSON stringified doc containing enrollment configuration.
Example:
enroll_all_students(json.dumps(doc))
enroll_students(self)
Description: Loops through applicants/students and creates enrollment entries.
Parameters:
self: Deserialized doc.
Example:
enroll_students(doc)
17. Batch and Inventory Automation
auto_close_dn()
Description: Auto-closes Delivery Notes based on the customer-specific cutoff period. Runs on schedule.
Parameters: None
Example:
auto_close_dn()
batch_splitting(doc, method)
Description: Splits and assigns item quantities from available batches during sales invoice creation.
Parameters:
doc: Sales Invoice document.method: Frappe event method (e.g., before_insert).
Example:
batch_splitting(sales_invoice_doc, "before_insert")
get_item_duplicates(source_doc)
Description: Separates single and duplicated item entries from a document.
Parameters:
source_doc: Sales Invoice or similar doc.
Example:
singles, duplicates = get_item_duplicates(doc)
get_batch_per_item(item_code, posting_date, warehouse)
Description: Queries the most recent valid batch quantities for an item.
Parameters:
item_code(str): Item code.posting_date(str): Posting date.warehouse(str): Warehouse name.
Example:
batches = get_batch_per_item("ITEM-001", "2025-04-01", "WH-001")
18. Tax and Fee Utilities
get_tax_category(company, account)
Description: Retrieves the tax category for a given account under a specific company.
Parameters:
company(str): Company name.account(str): Account name.
Example:
tax_cat = get_tax_category("Company A", "Tax Account")
get_fee_structure(program, academic_year)
Description: Fetches a fee structure based on program and academic year.
Parameters:
program(str): Program name.academic_year(str): Academic year.
Example:
fee_structure = get_fee_structure("BSc CS", "2024-2025")
19. Warehouse Utilities
get_child_warehouses(warehouse)
Description: Returns all child warehouses under the specified warehouse.
Parameters:
warehouse(str): Parent warehouse name.
Example:
children = get_child_warehouses("Stores")
get_all_warehouses()
Description: Returns a list of all warehouses in the system.
Parameters: None
Example:
warehouses = get_all_warehouses()
20. Miscellaneous Utilities
get_stock_uom(item_code)
Description: Returns the stock UOM for a specific item.
Parameters:
item_code(str): Item code.
Example:
uom = get_stock_uom("ITEM-001")
get_default_income_account(item_code, company)
Description: Returns the default income account for an item and company.
Parameters:
item_code(str): Item code.company(str): Company name.
Example:
account = get_default_income_account("ITEM-001", "My Company")
get_expense_account(item_code, company)
Description: Returns the default expense account for an item and company.
Parameters:
item_code(str): Item code.company(str): Company name.
Example:
account = get_expense_account("ITEM-001", "My Company")
get_default_cost_center(item_code, company)
Description: Returns the default cost center for a given item and company.
Parameters:
item_code(str): Item code.company(str): Company name.
Example:
cost_center = get_default_cost_center("ITEM-001", "My Company")