ERPNext
Lignes API personnalisées dans un modèle de rapport financier
La source API personnalisée appelle une fonction du serveur, dans une application installée. Ce n'est pas un appel direct à une adresse HTTP.
Quand l'utiliser
Nova veut une ligne de rapport de gestion que les catégories de compte seules ne produisent pas : un indicateur d'exploitation ajusté du budget, calculé par une application personnalisée installée. La valeur doit apparaître à côté des lignes de comptes standard et rester disponible pour les formules suivantes.
Une ligne de modèle de rapport financier dont la source de données est API personnalisée appelle une fonction Python approuvée, côté serveur. Utilisez-la seulement quand les lignes Données de compte et Montant calculé ne peuvent pas exprimer le besoin. C'est une fonction avancée pour les développeurs. Ce n'est pas un moyen d'appeler un point HTTP externe depuis le rapport.
Le site doit pouvoir installer et déployer l'application Frappe personnalisée. La fonction Python de niveau module s'y implémente et s'y teste. Confirmez ses performances, ses droits, son accès aux données et sa gestion d'erreur. Identifiez le modèle qui a besoin de la ligne.
Ajouter la ligne
- Ouvrez le modèle de rapport financier.
- Ajoutez une ligne dans les lignes du rapport et ouvrez son éditeur.
- Posez la source de données sur API personnalisée.
- Saisissez un chemin Python pointé, par exemple my_app.financial_report_api.get_budget_variance.
- Posez une référence de ligne si des formules ultérieures ont besoin de la valeur renvoyée.
- Configurez l'inversion de signe, Masquer si zéro, Ligne masquée, Inclure dans les graphiques et le type de valeur, selon le besoin.
- Enregistrez le modèle et lancez son rapport financier.
ERPNext peut passer les filtres du rapport, les périodes générées et la ligne courante. La fonction renvoie une valeur numérique par période, dans le même ordre. L'exemple officiel appelle une fonction de calcul que l'application doit fournir. Il ne définit pas cette fonction de calcul.
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| Exigence | Raison |
|---|---|
| Liste de valeurs numériques | Le rapport a besoin d'un montant affichable par période |
| Même longueur que les périodes | Chaque période affichée reçoit exactement un résultat |
| Même ordre que les périodes | Les valeurs s'alignent sur leurs en-têtes |
| Référence de ligne stable | Les lignes calculées suivantes utilisent le résultat sans ambiguïté |
Le chemin a la forme application.module.methode. La fonction doit exister dans une application installée. Le décorateur whitelist n'est pas exigé pour le seul appel du rapport. Les scripts serveur ne sont pas pris en charge pour ces lignes. ERPNext traite les lignes API personnalisée avant les résultats de comptes et de formules : elles ne doivent pas dépendre de lignes ultérieures du modèle.
Validez les filtres, utilisez des requêtes conscientes des droits là où c'est nécessaire, évitez de renvoyer un détail sensible, et bornez les requêtes. Testez les périodes sans données, plusieurs périodicités, la séparation des sociétés, les devises étrangères, les grandes plages de dates et les cas d'erreur. Rapprochez le résultat d'un calcul indépendant avant de publier le modèle.
Dépannage
Le chemin est rejeté. Utilisez un chemin de module pointé complet, et confirmez que la fonction est définie au niveau du module, dans une application installée.
La ligne affiche des zéros. Relisez le journal d'erreurs pour une erreur d'API personnalisée, confirmez qu'une valeur numérique a été renvoyée par période, et testez la fonction avec les mêmes filtres de rapport.
Une ligne calculée ne peut pas utiliser le résultat. Donnez à la ligne API une référence unique, et utilisez cette référence exacte dans la formule suivante.
Questions fréquentes
La ligne n'appelle pas directement une API REST publique. Le modèle appelle une fonction Python sur le serveur ERPNext. Cette fonction contrôlée peut s'intégrer à un autre système selon la conception de sécurité et de fiabilité de l'application.
La fonction ne devrait pas modifier les données comptables. Une fonction de reporting se limite à la lecture. Créer ou changer des transactions pendant l'exécution du rapport rendrait les résultats dangereux et imprévisibles.
Si la fonction lève une erreur, ERPNext enregistre l'erreur et peut remplir la ligne de zéros. Traitez cet état comme un calcul de rapport en échec, et enquêtez avant de partager la sortie.