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 getbeelCreate 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 firstResponses 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 400webhooks.verify(payload, header, secret) returns True or False; signatures older than 5 minutes are refused. See Webhooks.