# BeeL Python SDK

[![PyPI](https://img.shields.io/pypi/v/beel-sdk.svg)](https://pypi.org/project/beel-sdk/)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Official Python SDK for the [BeeL](https://beel.es) invoicing API. Fully typed.

## Installation

```bash
pip install beel-sdk
```

## Quick Start

```python
from beel import BeeL

# The client validates your API key on construction
beel = BeeL('beel_sk_live_...')

# List invoices
invoices = beel.invoices.list()

# Get a specific invoice
invoice = beel.invoices.get('550e8400-e29b-41d4-a716-446655440000')
```

## Usage

### Invoices

```python
# List with filters
invoices = beel.invoices.list(page=1, limit=20, status='paid')

# Create
from beel_generated.models import CreateInvoiceRequest, CreateInvoiceRequestLinesInner

invoice = beel.invoices.create(CreateInvoiceRequest(
    customer_id='uuid',
    issue_date='2026-03-10',
    lines=[CreateInvoiceRequestLinesInner(
        description='Service',
        quantity=1,
        unit_price=100
    )]
))

# Issue, send, mark paid
beel.invoices.issue('invoice-id')
beel.invoices.send_email('invoice-id', SendEmailRequest(to='client@example.com'))
beel.invoices.mark_paid('invoice-id', MarkInvoicePaidRequest(payment_date='2026-03-10'))

# Download PDF
pdf = beel.invoices.download_pdf('invoice-id')
```

### Customers

```python
customers = beel.customers.list()
created = beel.customers.create(CreateCustomerRequest(name='ACME', nif='B12345678'))
beel.customers.update('id', UpdateCustomerRequest(email='new@acme.com'))
beel.customers.delete('id')
```

### Products

```python
products = beel.products.list()
results = beel.products.search(q='hosting')
```

### Series

```python
series = beel.series.list()
beel.series.set_default('series-id')
```

### Configuration

```python
tax = beel.config.get_tax_configuration()
vf = beel.config.get_verifactu_configuration()
```

## Error Handling

```python
from beel import BeeL, BeeLError

try:
    beel = BeeL('invalid_key')
except BeeLError as e:
    print(e)              # "Invalid API key..."
    print(e.status_code)  # 401
```

## Configuration

```python
# Production (default)
beel = BeeL('beel_sk_live_...')

# Test environment
beel = BeeL('beel_sk_live_...', base_url='https://test.beel.es/api')

# Skip validation
beel = BeeL('beel_sk_live_...', skip_validation=True)

# Context manager
with BeeL('beel_sk_live_...') as beel:
    invoices = beel.invoices.list()
```

## Requirements

- Python 3.9+

## Links

- [API Reference](https://beel.es/api-reference)
- [Website](https://beel.es)
- [Support](mailto:info@beel.es)
