Рядки з власним API у шаблоні фінансового звіту

Nova Industries хоче мати в управлінському звіті рядок, який неможливо отримати лише з категорій рахунків: спеціалізований операційний показник із поправкою на бюджет, що його розраховує встановлений власний застосунок. Значення має стояти поруч зі стандартними рядками рахунків і бути доступним для подальших формул.

Рядок шаблону фінансового звіту, у якого «Джерело даних» має значення Власний API, викликає затверджену серверну функцію на Python. Використовуйте його лише тоді, коли вимогу неможливо реалізувати рядками «Дані рахунку» та «Розрахована сума». Це розширена можливість для розробників, а не спосіб викликати зовнішню HTTP-адресу зі звіту.

Перш ніж почати

Використовуйте сайт, на якому можна встановити та розгорнути власний застосунок Frappe.
Реалізуйте та протестуйте функцію Python на рівні модуля в цьому застосунку.
Перевірте продуктивність функції, права доступу, доступ до даних і обробку помилок.
Створіть або знайдіть шаблон фінансового звіту, якому потрібен цей рядок.

Список шаблонів фінансових звітів перед додаванням розширеного рядка «Власний API»

Як додати рядок «Власний API»

Форма шаблону фінансового звіту, де налаштовується рядок звіту з власним API

Відкрийте шаблон фінансового звіту.
Додайте рядок у таблицю «Рядки звіту» і відкрийте редактор рядка.
У полі «Джерело даних» виберіть Власний API.
Введіть шлях Python через крапку, наприклад my_app.financial_report_api.get_budget_variance.
Якщо наступним рядкам із формулами потрібне повернене значення, задайте «Посилання на рядок».
За потреби налаштуйте «Змінити знак», «Приховувати, якщо нуль», «Прихований рядок», «Включати в діаграми» і «Тип значення».
Збережіть шаблон і сформуйте відповідний фінансовий звіт.

Контракт функції

ERPNext може передати у функцію фільтри звіту filters, сформовані періоди periods і поточний рядок row. Функція має повернути по одному числовому значенню для кожного періоду в тому самому порядку.

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:
        variance = calculate_variance(
            company=filters.get("company"),
            from_date=period.from_date,
            to_date=period.to_date,
        )
        values.append(flt(variance))

    return values

Вимоги до поверненого значення

Вимога	Причина
Список числових значень	Звітові потрібна одна сума для відображення на кожен період.
Та сама довжина, що й у periods	Кожен відображений період має отримати рівно один результат.
Той самий порядок, що й у periods	Значення мають відповідати своїм заголовкам.
Стабільне «Посилання на рядок»	Наступні розрахункові рядки безпечно використовують результат API.

Важливі особливості

Шлях має бути у форматі app.module.method. Функція повинна існувати у встановленому застосунку. Декоратор @frappe.whitelist() не обов'язковий, якщо функцію викликає лише звіт. Серверні скрипти для рядків «Власний API» не підтримуються. ERPNext обробляє рядки «Власний API» раніше за рядки рахунків і формул, тож вони не повинні залежати від наступних рядків шаблону.

Безпека й тестування функції

Перевіряйте значення фільтрів, за потреби використовуйте запити з урахуванням прав доступу, не повертайте конфіденційних подробиць і обмежуйте обсяг запитів. Протестуйте періоди без даних, різну періодичність, розділення організацій, іноземні валюти, великі діапазони дат і ситуації з помилками. Перш ніж опублікувати шаблон, звірте результат із незалежним розрахунком.

Вирішення проблем

Шлях до API відхилено

Використовуйте повний шлях до модуля через крапку і переконайтеся, що функцію визначено на рівні модуля у встановленому застосунку.

Рядок показує нулі

Перегляньте журнал помилок на предмет помилки власного API, переконайтеся, що функція повернула по одному числовому значенню на період, і протестуйте її з тими самими фільтрами звіту.

Розрахунковий рядок не може використати результат

Задайте рядку «Власний API» унікальне «Посилання на рядок» і використовуйте саме це посилання в подальшій формулі.

Часті запитання

Чи може рядок напряму викликати публічний REST API?

Шаблон викликає функцію Python на сервері ERPNext. Ця контрольована функція може інтегруватися з іншою системою — відповідно до вимог безпеки та надійності вашого застосунку.

Чи може функція змінювати бухгалтерські дані?

Функція для звітності має лише читати дані. Створення чи зміна операцій під час формування звіту зробили б результати небезпечними й непередбачуваними.

Що станеться, якщо функція згенерує помилку?

ERPNext запише помилку і може заповнити рядок нулями. Вважайте це невдалим розрахунком звіту і з'ясуйте причину, перш ніж передавати звіт іншим.

Пов'язані теми

Переклад сторінки «Using Custom API Rows in Financial Report Template» з документації ERPNext. © Frappe Technologies Pvt. Ltd., ліцензія CC BY-SA 3.0. Переклад — OpenOblik, на тих самих умовах. Переклад машинний, вичитка триває: помітили неточність — напишіть нам.

Документація ERPNext