GetbeelDocs

Python SDK

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

getbeel covers the whole API. 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+.

pip install getbeel

Create and send an invoice

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. 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

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 in snake_case.

Idempotency and errors

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 POSTs and reads are retried max_retries times on 408, 429 (after Retry-After), 5xx, network errors and 409 idempotency_key_in_use; other POSTs only on 429. Subclasses: InvalidRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, RateLimitError, APIError, APIConnectionError.

Pagination and client companies

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

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.

On this page