在财务报表模板中使用自定义API行

将数据来源设置为“自定义 API”的行，其值来自服务器端的 Python 函数，而不是账户筛选条件或公式。

这适用于“资产负债表”、“利润表”、“现金流量表”和“自定义财务报表”所使用的模板。

何时使用

当报表行依赖于自定义业务逻辑、预算数据、外部聚合或标准账户筛选条件无法提供的计算时，请使用 Custom API 行。

如果需要将该结果与其他报表行合并，请添加一个数据来源设置为“计算金额”的后续行。

如何设置

1. 打开您的财务报表模板。
2. 在报表行项目表中添加一行。
3. 将数据来源设置为“自定义 API”。
4. 在公式或账户筛选条件中，输入一个点分隔的 Python 路径，例如 my_app.financial_report_api.get_budget_variance。
5. 可选：如果后续公式行需要重用此结果，请设置行引用。
6. 可选：像在其他行上一样使用反转符号、为零时隐藏、隐藏行（仅供内部使用）、包含在图表中和值类型。

ERPNext 如何调用您的函数

ERPNext 在服务器上调用目标函数，并传递以下参数：

• filters：当前报表筛选条件，作为一个类似字典的对象
• periods：为报表生成的期间列表
• row：当前的财务报表行文档

periods 中的每个项目包含以下值：

• from_date
• to_date
• key
• label

您的函数可以接受所有三个参数，也可以只接受需要的参数。

示例

from frappe.utils import flt

def get_budget_variance(filters=None, periods=None, row=None):
    filters = filters or {}
    periods = periods or []

    values = []

    for period in periods:
        # Replace this placeholder logic with your own query or calculation.
        variance = 0.0
        values.append(flt(variance))

    return values

返回值要求

• 返回一个数值列表。
• 为 periods 中的每个期间返回一个值。
• 返回值的顺序必须与 periods 的顺序一致。

如果该行有行引用，后续公式行可以使用该代码，例如 API001 + SALES001。

重要说明

• 路径必须采用 app.module.method 格式。
• 目标应是一个已安装应用中模块级别的 Python 函数。
• 除非您还想从 /api/method 调用同一函数，否则此功能不需要 @frappe.whitelist()。
• 目前 Custom API 行不支持服务器脚本。
• Custom API 行在基于账户和基于公式的行之前处理，因此它们不应依赖于其他模板行的结果。
• 如果函数引发错误，ERPNext 会写入一条错误日志条目，并用零填充该行。

故障排除

• 如果看到关于 API 路径的验证错误，请检查路径是否写为 app.module.method。
• 如果看到“方法未找到”，请确认该函数存在于该模块中，并且该应用已安装在站点上。
• 如果该行显示为零，请检查错误日志中是否有 Custom API Error 条目。
• 如果公式行无法使用 API 结果，请确保源行具有行引用，并且公式中使用的代码完全一致。