SDK Python
Il client Python ufficiale, tipizzato, con una sola dipendenza (httpx).
getbeel copre tutta l'API. Aggiunge un Idempotency-Key a ogni POST che lo supporta, riprova i limiti di frequenza e gli errori del server, lancia errori tipizzati, scorre le liste e verifica le firme dei webhook. Python 3.9+.
pip install getbeelCrea e invia una fattura
from getbeel import Getbeel
client = Getbeel() # legge GETBEEL_API_KEY; oppure Getbeel(api_key="gb_test_...")
bozza = client.invoices.create(
tipo_documento="TD01",
currency="EUR",
customer={
"denominazione": "Bianchi S.p.A.",
"partita_iva": "01234567890",
"country": "IT",
"codice_destinatario": "ABCDE12",
},
lines=[{"description": "Consulenza, ottobre", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00"}],
)
inviata = client.invoices.send(bozza["id"]) # mostra la bozza e chiedi l'OK primaLe risposte sono dizionari con i campi del riferimento API. I corpi si passano come dizionario, come argomenti con nome o in entrambi i modi. Il parametro from si scrive from_.
Opzioni: Getbeel(api_key=None, base_url=None, company=None, timeout=60.0, max_retries=2, http_client=None); base_url predefinito: GETBEEL_BASE_URL, poi https://www.getbeel.com/api/v1.
Risorse
me(), invoices, recurring_invoices, received_invoices, bank_statements (upload accetta un percorso, dei byte o un 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). I nomi dei metodi sono quelli dell'SDK TypeScript in snake_case.
Idempotenza ed errori
from getbeel import GetbeelError, NotFoundError
client.invoices.send(bozza["id"], idempotency_key=f"send-{bozza['id']}")
try:
client.invoices.get("inesistente")
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)Ogni POST che supporta l'idempotenza riceve un Idempotency-Key casuale, lo stesso nei nuovi tentativi automatici e riportato in e.idempotency_key se fallisce. Quei POST e le letture vengono riprovati max_retries volte su 408, 429 (dopo Retry-After), 5xx, errori di rete e 409 idempotency_key_in_use; gli altri POST solo su 429. Sottoclassi: InvalidRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, RateLimitError, APIError, APIConnectionError.
Paginazione e aziende clienti
for fattura in client.invoices.iter_all(status="delivered"):
print(fattura["number"])
bianchi = client.with_company("COMPANY_ID") # header Getbeel-Company
bianchi.invoices.list()Webhook
from getbeel import webhooks, WebhookSignatureError
try:
event = webhooks.construct_event(corpo_grezzo, headers["Getbeel-Signature"], os.environ["GETBEEL_WEBHOOK_SECRET"])
except WebhookSignatureError:
... # rispondi 400webhooks.verify(payload, header, secret) restituisce True o False; le firme più vecchie di 5 minuti sono rifiutate. Vedi Webhook.