Overview
This node interacts with the Asaas API to manage customer data. Specifically, for the Cliente (Customer) resource and the Listar (List) operation, it retrieves a list of customers from the Asaas platform. It supports filtering and pagination, allowing users to fetch subsets of customers based on criteria such as name, email, CPF/CNPJ (Brazilian individual/company tax IDs), group name, or external reference.
Common scenarios:
- Synchronizing customer lists from Asaas into other systems.
- Fetching filtered customer data for reporting or analysis.
- Implementing workflows that require batch processing of customer records.
Practical example:
- A user wants to retrieve up to 100 customers who belong to a specific group and have an email address containing "example.com". They can set the limit to 100 and use the "Nome Do Grupo" filter to specify the group name, then process the returned customers in subsequent workflow steps.
Properties
| Name | Meaning |
|---|---|
| Limite | Max number of results to return (minimum 1). |
| Offset | Number of customers to skip before starting to collect the result set (for pagination). |
| Filtros Adicionais | Additional filters to narrow down the customer list: |
| - CPF/CNPJ | Filter customers by their CPF or CNPJ identifier. |
| Filter customers by email address. | |
| - Nome | Filter customers by customer name. |
| - Nome Do Grupo | Filter customers by the name of the group they belong to. |
| - Referência Externa | Filter customers by an external reference identifier. |
Output
The output is an array of JSON objects, each representing a single customer retrieved from the Asaas API. Each object contains the customer's details as provided by the API, including but not limited to identifiers, contact information, and metadata.
If multiple customers are returned, each one is output as a separate item in the node's output array, preserving the pairing with the input item that triggered the request.
No binary data is output by this operation.
Dependencies
- Requires an API key credential for authenticating with the Asaas API.
- The node dynamically selects the API base URL depending on whether the environment is set to production or sandbox.
- Proper configuration of the API key and environment is necessary in n8n credentials settings.
Troubleshooting
Common issues:
- Invalid or missing API key will cause authentication errors.
- Using an incorrect environment setting may lead to unexpected responses or inability to connect.
- Providing invalid filter values might result in empty results or API errors.
Error messages:
- Authentication failures typically indicate problems with the API key or environment configuration.
- Rate limiting or quota exceeded errors may occur if too many requests are made in a short time.
- Validation errors from the API when filter parameters are malformed or unsupported.
Resolutions:
- Verify that the API key credential is correctly configured and active.
- Confirm the environment setting matches the intended API endpoint (production vs sandbox).
- Double-check filter inputs for correctness and supported formats.
Links and References
- Asaas API Documentation (official API docs)
- n8n Documentation (for general usage and credential setup)