Alegra (Unofficial - BETA) icon

Alegra (Unofficial - BETA)

Consume Alegra API - UNOFFICIAL BETA community node. NOT officially supported by Alegra.

Actions37

Overview

The node integrates with the Alegra API to manage payments. Specifically, the "Payment" resource with the "Get Many" operation allows users to retrieve multiple payment records from their Alegra account. This is useful for financial reporting, reconciliation, or auditing purposes where you need to fetch a list of payments filtered by various criteria.

Typical use cases include:

  • Fetching all payments within a specific date range.
  • Retrieving payments filtered by type (income or expense).
  • Filtering payments related to a particular contact or bank account.
  • Sorting payments by date or ID in ascending or descending order.
  • Limiting the number of results returned for performance or pagination.

For example, a user might want to get all income payments made in the last month for a specific client, ordered by date descending, to generate a report.

Properties

Name Meaning
Return All Whether to return all matching payment records or limit the number of results.
Limit Maximum number of payment records to return if not returning all. Value between 1 and 100.
Filters Collection of filters to narrow down the payments retrieved:
- Start Date Filter payments from this date (inclusive).
- End Date Filter payments until this date (inclusive).
- Type Filter by payment type. Options:
• All (no filter)
• Income
• Expense
- Contact Name or ID Filter payments by a specific contact. Can select from a loaded list or specify an ID via expression.
- Bank Account Name or ID Filter payments by a specific bank account. Can select from a loaded list or specify an ID via expression.
- Order By Field to order the results by. Options:
• Date
• ID
- Order Direction Direction to order the results. Options:
• Ascending
• Descending

Output

The output is an array of JSON objects, each representing a payment record retrieved from Alegra. Each object contains the full payment data as returned by the Alegra API, including fields such as payment date, type, associated contact, bank account, invoices linked, currency, observations, annotations, exchange rate, categories, retentions, and other payment details.

No binary data is output by this operation.

Example snippet of output JSON structure (simplified):

{
  "id": 123,
  "date": "2024-05-01",
  "type": "in",
  "client": {
    "id": 456,
    "name": "Client Name"
  },
  "bankAccount": {
    "id": 789,
    "name": "Main Account"
  },
  "invoices": [...],
  "currency": {
    "code": "COP"
  },
  "observations": "Payment received",
  "exchangeRate": 1.0,
  "categories": [...],
  "retentions": [...]
}

Dependencies

  • Requires an API key credential for authenticating with the Alegra API.
  • The node uses the Alegra API base URL configured in the credential environment.
  • The node depends on n8n's HTTP request helper with authentication support.
  • For dynamic options like contacts and bank accounts, it calls Alegra endpoints to load available options.

Troubleshooting

  • Authentication errors: Ensure the API key credential is correctly configured and has necessary permissions.
  • Invalid filter values: Dates must be valid ISO datetime strings; IDs must correspond to existing contacts or bank accounts.
  • Limit out of range: The limit property must be between 1 and 100 when not returning all.
  • API rate limits: If many requests are made, the Alegra API may throttle; consider using "Return All" carefully or implement delays.
  • Empty results: Check that filters are correct and that there are payments matching the criteria.
  • Unknown errors: The node wraps errors from the API and throws them as node operation errors; check the error message for details.

Links and References

Discussion