FireFly III

Overview

The node interacts with the FireFly III API to retrieve financial insights based on transaction data. Specifically, the "General" resource with the "Insights" operation allows users to fetch summarized financial data grouped by various criteria such as asset accounts, expense accounts, categories, tags, budgets, and bills. This is useful for analyzing spending patterns, income sources, transfers, and overall financial health over a specified date range.

Common scenarios include:

• Generating reports on expenses or income grouped by category or tag.
• Tracking transfers grouped by asset accounts.
• Viewing total amounts for specific transaction types within a custom date range.
• Filtering insights by specific accounts, categories, tags, budgets, or bills.

Practical example:
A user wants to see their total expenses grouped by category for the last month, filtered to only include certain accounts and tags. They configure the node to request "Expenses" insight, group by "Category," set the date range filters accordingly, and specify account and tag IDs to narrow down the data.

Properties

Output

The output is a JSON object containing the insight data returned by the FireFly III API. The structure depends on the selected insight type and grouping but generally includes aggregated financial figures grouped according to the chosen criteria.

Example output structure (simplified):

{
  "grouping_key": {
    "id": "string",
    "name": "string",
    "amount": number,
    ...
  },
  "total": number,
  ...
}

Each key corresponds to a group (e.g., a category or asset account), with associated aggregated amounts and metadata.

This node does not output binary data for the Insights operation.

Dependencies

• Requires an active connection to the FireFly III API.
• Needs an API authentication token configured in n8n credentials (an OAuth2 or API key credential).
• The node uses internal helper functions to make HTTP requests to the FireFly III endpoints.

Troubleshooting

• Invalid or missing API credentials: Ensure that the API authentication token is correctly configured in n8n credentials.
• Incorrect date formats: Date filters must be in YYYY-MM-DD format; otherwise, the API may reject the request.
• Unsupported groupings for transaction types: Some group-by options do not work with all transaction types (e.g., grouping by budget might not apply to transfers). Consult the FireFly III API documentation if unexpected empty results occur.
• Malformed comma-separated ID lists: When specifying multiple IDs (accounts, categories, tags, budgets, bills), ensure they are properly comma-separated without extra spaces or invalid characters.
• API rate limits or connectivity issues: Network problems or API rate limiting can cause errors; verify network access and API usage policies.

Links and References

• FireFly III API Documentation
• FireFly III Search Feature Documentation