# Python SDK (https://docs.getbeel.com/en/api/sdk-python)

The official Python client, typed, with one dependency (httpx).

`getbeel` covers the whole [API](/en/api/reference). It adds an `Idempotency-Key` to every `POST` that supports one, retries rate limits and server errors, raises typed errors, pages through lists and verifies webhook signatures. Python 3.9+.

```bash
pip install getbeel
```

## Create and send an invoice [#create-and-send-an-invoice]

```python
from getbeel import Getbeel

client = Getbeel()  # reads GETBEEL_API_KEY; or Getbeel(api_key="gb_test_...")

draft = client.invoices.create(
    tipo_documento="TD01",
    currency="EUR",
    customer={
        "denominazione": "Bianchi S.p.A.",
        "partita_iva": "01234567890",
        "country": "IT",
        "codice_destinatario": "ABCDE12",
    },
    lines=[{"description": "Consulting, October", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00"}],
)

sent = client.invoices.send(draft["id"])  # show the draft and get an OK first
```

Responses are dicts with the fields of the [API reference](/en/api/reference). Bodies can be a dict, keyword arguments or both. The query parameter `from` is `from_`.

Options: `Getbeel(api_key=None, base_url=None, company=None, timeout=60.0, max_retries=2, http_client=None)`; `base_url` defaults to `GETBEEL_BASE_URL`, then `https://www.getbeel.com/api/v1`.

## Resources [#resources]

`me()`, `invoices`, `recurring_invoices`, `received_invoices`, `bank_statements` (`upload` takes a path, bytes or a file), `bank_transactions`, `reconciliations`, `unmatched`, `bank_connections`, `connections`, `companies`, `taxes` (`calendar`, `calendar_ics`, `vat_position`, `vat_registers`, `vat_settlement`, `report`, `accountant_export`), `filings` (`prepare`, `list`, `get`, `file`, `upload_receipt`). Method names follow the [TypeScript SDK](/en/api/sdk-typescript) in snake_case.

## Idempotency and errors [#idempotency-and-errors]

```python
from getbeel import GetbeelError, NotFoundError

client.invoices.send(draft["id"], idempotency_key=f"send-{draft['id']}")

try:
    client.invoices.get("missing")
except NotFoundError as e:
    print(e.code, e.message)
except GetbeelError as e:
    print(e.status, e.type, e.code, e.param, e.request_id)
```

Every `POST` that supports idempotency gets a random `Idempotency-Key`, kept across automatic retries and returned in `e.idempotency_key` when it fails. Those `POST`s and reads are retried `max_retries` times on `408`, `429` (after `Retry-After`), `5xx`, network errors and `409 idempotency_key_in_use`; other `POST`s only on `429`. Subclasses: `InvalidRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `APIError`, `APIConnectionError`.

## Pagination and client companies [#pagination-and-client-companies]

```python
for invoice in client.invoices.iter_all(status="delivered"):
    print(invoice["number"])

bianchi = client.with_company("COMPANY_ID")  # Getbeel-Company header
bianchi.invoices.list()
```

## Webhooks [#webhooks]

```python
from getbeel import webhooks, WebhookSignatureError

try:
    event = webhooks.construct_event(raw_body, headers["Getbeel-Signature"], os.environ["GETBEEL_WEBHOOK_SECRET"])
except WebhookSignatureError:
    ...  # answer 400
```

`webhooks.verify(payload, header, secret)` returns `True` or `False`; signatures older than 5 minutes are refused. See [Webhooks](/en/api/webhooks).
