# n8n-nodes-alegra-unofficial (BETA)

⚠️ **IMPORTANT DISCLAIMERS:**
- This is an **UNOFFICIAL** community node, NOT created or supported by Alegra
- This node is in **BETA** - functionality may change and bugs may exist
- Use at your own risk in production environments
- Always test thoroughly with your Alegra sandbox account first

This is an unofficial n8n community node for [Alegra](https://www.alegra.com/), a cloud-based accounting software popular in Latin America. It provides integration with Alegra's API to manage invoices, contacts, items, payments, and more.

## Features

This node allows you to:

### Contacts
- Create, read, update, and delete contacts (clients and providers)
- Filter contacts by name, type, identification, etc.
- Manage contact details including addresses, phone numbers, and custom fields

### Invoices
- Create electronic invoices with multiple items
- Get and list invoices with various filters
- Send invoices by email
- Update invoice details
- Support for Colombian electronic invoicing requirements

### Items (Products/Services)
- Create and manage products and services
- Set prices, taxes, and categories
- Track inventory for products
- Filter items by type, status, category, etc.

### Payments
- Record payments for invoices
- Manage income and expenses
- Support for multiple payment methods
- Handle retentions and categories

### Estimates/Quotes
- Create and manage estimates
- Convert estimates to invoices
- Send estimates by email
- Track estimate status

### Taxes
- Create and manage tax configurations
- Support for general taxes, retentions, and compound taxes
- Set tax percentages and descriptions

### Bank Accounts
- Create and manage bank accounts
- Transfer money between accounts
- Track balances and transactions
- Support multiple currencies

## Installation

### Community Nodes (Recommended)

1. Go to **Settings** > **Community Nodes**
2. Select **Install**
3. Enter `n8n-nodes-alegra-unofficial` in the input field
4. Select **Install**

### Manual Installation

1. Navigate to your n8n installation directory
2. Install the node:
   ```bash
   npm install n8n-nodes-alegra-unofficial
   ```
3. Restart n8n

### Docker Installation

If you're using n8n with Docker, you'll need to build a custom image:

1. Create a Dockerfile:
   ```dockerfile
   FROM n8nio/n8n
   USER root
   RUN npm install -g n8n-nodes-alegra-unofficial
   USER node
   ```

2. Build and run:
   ```bash
   docker build -t n8n-custom .
   docker run -it --rm --name n8n -p 5678:5678 n8n-custom
   ```

### Docker Compose (Auto-start on boot, recommended for development)

1. Crea un archivo llamado `docker-compose.yml` en la raíz de tu proyecto con el siguiente contenido:

```yaml
version: "3.8"
services:
  n8n:
    image: n8nio/n8n
    container_name: n8n
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_PROTOCOL=https
      - N8N_SSL_KEY=/etc/ssl/private/n8n-local.key
      - N8N_SSL_CERT=/etc/ssl/certs/n8n-local.crt
      - N8N_ENABLE_COMMUNITY_NODES=true
    volumes:
      - ~/.n8n:/home/node/.n8n
      - ~/certs-n8n/n8n-local.crt:/etc/ssl/certs/n8n-local.crt
      - ~/certs-n8n/n8n-local.key:/etc/ssl/private/n8n-local.key
```

2. Inicia n8n en segundo plano con:

```bash
docker compose up -d
```

3. Para detenerlo:

```bash
docker compose down
```

Con esta configuración, n8n se reiniciará automáticamente cada vez que prendas tu PC (si Docker Desktop está configurado para iniciarse con Windows/Linux). Puedes modificar variables, puertos o volúmenes fácilmente en el archivo `docker-compose.yml`.

## Authentication

1. In your Alegra account, go to **Settings** > **API - Integrations with other systems**
2. Copy your email and API token
3. In n8n, create new Alegra credentials:
   - **Email**: Your Alegra account email
   - **API Token**: Your API token from Alegra
   - **Environment**: Choose between Production or Sandbox

## Usage

1. Add the Alegra node to your workflow
2. Select the resource you want to work with (Contact, Invoice, Item, etc.)
3. Choose the operation (Create, Get, Update, Delete, etc.)
4. Configure the required and optional fields
5. Connect your Alegra credentials

### Example: Creating an Invoice

```javascript
{
  "resource": "invoice",
  "operation": "create",
  "date": "2024-01-15",
  "dueDate": "2024-02-15",
  "client": "123", // Client ID
  "paymentForm": "CASH",
  "paymentMethod": "BANK_TRANSFER",
  "generateStamp": true,
  "items": [
    {
      "id": "456", // Item ID
      "price": 100000,
      "quantity": 2,
      "description": "Professional Services"
    }
  ]
}
```

## Supported Countries

This node supports Alegra accounts from:
- 🇨🇴 Colombia
- 🇲🇽 Mexico
- 🇵🇪 Peru
- 🇨🇱 Chile
- 🇦🇷 Argentina
- 🇵🇦 Panama
- 🇨🇷 Costa Rica

## Error Handling

The node includes proper error handling for common scenarios:
- Invalid credentials
- Required fields validation
- API rate limits
- Network errors

Enable "Continue On Fail" in the node settings to handle errors gracefully in your workflows.

## Support

This is an unofficial community node. For issues related to:
- **This node**: Please create an issue on [GitHub](https://github.com/yourusername/n8n-nodes-alegra-unofficial)
- **Alegra API**: Check the [official Alegra API documentation](https://developer.alegra.com/)
- **n8n**: Visit the [n8n community forum](https://community.n8n.io/)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License

## ⚠️ Important Disclaimers

1. **UNOFFICIAL**: This node is NOT affiliated with, officially maintained, or endorsed by Alegra
2. **BETA VERSION**: This is a beta release (v0.1.0-beta) and has not been fully tested in all scenarios
3. **NO WARRANTY**: This software is provided "as is" without any warranty
4. **USE AT YOUR OWN RISK**: The authors are not responsible for any data loss or issues
5. **TEST FIRST**: Always test with Alegra's sandbox environment before using in production

### Beta Limitations
- Not all API endpoints may be implemented
- Error handling may not cover all edge cases
- Breaking changes may occur in future versions
- Limited testing with different Alegra account configurations